Skip to content

dimagi-internal/ace / skills/app-test-cases

app-test-cases

Verified

Turn PDD user journeys into Maestro test recipes with real selectors from a Nova-built app. Needs the app-journeys doc and the Nova app.

FileKindSize
SKILL.mdskill md156.9 KB
---
name: app-test-cases
description: >
  Turn PDD user journeys into Maestro test recipes with real selectors from a Nova-built app.
  Needs the app-journeys doc and the Nova app.
disable-model-invocation: false
---

# App Test Cases

**Worker role (multi-role runs):** when the dispatch carries a `worker_role: {key, label}` block, scope this run to that role's apps and its part of the PDD, and read and write every `3-commcare/` (or `4-connect/`) file at the same name under `3-commcare/roles/<key>/` (`4-connect/roles/<key>/`). No block = a single-role run, unchanged. Contract: [`skills/_worker-roles.md`](../_worker-roles.md).

Binds Phase 1 UX intent to Phase 3 built structure. Runs after Nova
finishes both apps, before `app-release` — so the recipes exist when
Phase 6 needs them.

## Related skills

- **Successor to:** `qa-plan` (retired in 0.10.x, replaced by this skill).
- **Consumes:** `pdd-to-app-journeys.md` from `pdd-to-app-journeys` (Phase 1).
- **Consumed by:** `app-screenshot-capture` (Phase 6, shallow) and
  `/ace:qa-deep` (full execution).

## Inputs

| Parameter | Used for | Resolver |
|---|---|---|
| `journeys_doc` | journey list + persona + per-journey pass criteria | explicit arg (a Drive file id); default: `2-scenarios/pdd-to-app-journeys.md`. On a live program with no journeys doc, write one first (`pdd-to-app-journeys` takes the same shape) |
| `learn_nova_app_id`, `deliver_nova_app_id` | the Nova apps to bind selectors against (either may be omitted to cover one app) | explicit arg; default: `3-commcare/pdd-to-learn-app_summary.md` and `pdd-to-deliver-app_summary.md` |
| `out_folder_id` | where the catalog and `recipes/` are written | explicit arg; default: the run's `3-commcare` folder |
| Nova MCP | authoritative form/field IDs to resolve into real Maestro selectors | read live: `get_app({app_id: <nova_app_id>})` |
| Static | recipe palette / templates | `mcp/mobile/recipes/static/` |
| **Selector map** | **the authoritative, live-calibrated source for screen IDs and selector behavior.** Rows carry `unverified: true` or a `Live-verified` note, so the map states its own confidence per row — DO NOT improvise selectors that contradict it. | `mcp/mobile/selectors/connect-<apkVersion>.yaml` (default `2.63.2`) |
| **Atlas** (partial) | narrative transition/side-effect notes only — sequence and side-effects, never identity. Its `## Provenance and coverage` table tags every surface `calibrated-2.63.2`, `carried-from-2.62.0-unverified`, or `uncovered`; read that tag before relying on a section. Where the atlas and the selector map disagree, **the selector map wins**; where the atlas says a surface is uncovered, check the palette recipes in `mcp/mobile/recipes/static/` before believing it. The carried-over surfaces are reproduced by reference from the older 2.62.0 atlas (its §§ 1-11) rather than restated. | `docs/mobile-atlas/connect-2.63.2.md` |

## Products

- `3-commcare/app-test-cases.yaml` — the full journey **catalog**: per-journey test entries for EVERY journey (smoke + deep), one per journey, exactly one `is_smoke: true` per app. The catalog documents the intended coverage; it lists every journey regardless of whether its recipe file exists yet.
- `3-commcare/recipes/journey-<app>[-<slug>].yaml` — a Maestro recipe **only for the `is_smoke: true` journeys** (the two smokes: `journey-learn-pass` → `journey-learn.yaml`, `journey-deliver-submit` → `journey-deliver.yaml`). The single `is_smoke: true` journey per app uses the bare name (`journey-learn.yaml`, `journey-deliver.yaml`). Each journey's `id` in `app-test-cases.yaml` is a meaningful `journey-`-prefixed kebab-case slug (`journey-learn-pass`, `journey-deliver-submit`) — see § Journey id convention; for a smoke journey, `recipe:` points at the descriptive file.

**Deep recipes are generated lazily — NOT at Phase 3.** Phase 6 (shallow, inside `/ace:run`) only ever walks the `is_smoke: true` journeys, one per app. The non-smoke (deep) journeys are consumed exclusively by `/ace:qa-deep`, which is a manual gate that is frequently not run. Authoring + persisting a Maestro recipe for every deep journey up front is therefore wasted work + clutter. So:

- This skill writes recipe files **only** for the smoke journeys.
- For every non-smoke (deep) journey, the catalog entry's `recipe:` value is the literal string `deferred` (NOT a path). `/ace:qa-deep` generates the missing deep recipes on demand — using the SAME composition rules in this SKILL.md (static palette + live `get_form` labels + selector-resolution gate) — the first time it runs against the run, because the Nova `app_id` and `get_form` still return the as-built app structure within a run (the "author before app-release freezes it" concern does not apply within a single run). See `commands/qa-deep.md § Stage B`. This is tracked as jjackson/ace#605.

### Journey id convention

Each journey's `id` is a **`journey-`-prefixed, meaningful kebab-case slug
derived from the journey's intent** — NOT a cryptic `J<n>` ordinal. The
form is `journey-<app>-<intent>`: the `id` **MUST begin with the literal
prefix `journey-`**, then the app (`learn` or `deliver`), then a short
kebab-case intent slug. The slug must be unique within the opp and stable
across re-runs. The `journey-` prefix makes the id self-describing
wherever it is listed — run artifacts, dashboards, screenshot labels,
smoke-subset lists, and verdicts all read meaningfully.

Canonical examples (use these verbatim when the journey matches; coin a
new intent-derived slug otherwise):

| `id` | What it covers |
|---|---|
| `journey-learn-pass` | Learn smoke — walk all modules + pass the final assessment first try |
| `journey-learn-retry` | answer a quiz question wrong, then retry and pass |
| `journey-deliver-submit` | Deliver smoke — a positive/eligible service-delivery visit |
| `journey-deliver-alt-answer` | a negative/ineligible visit (the "No" branch) |
| `journey-deliver-multiple` | multiple visits in one session (multi-stage archetype) |
| `journey-deliver-locked` | confirm Deliver is locked until Learn is complete |

Rules:
- The `id` always starts with the literal `journey-` prefix, then the
  app (`learn` / `deliver`), so both the journey-ness and the app
  membership are legible from the id alone.
- The `is_smoke: true` journey per app conventionally uses the simplest
  happy-path slug (`journey-learn-pass` for Learn,
  `journey-deliver-submit` for Deliver).
- Keep slugs ≤ ~40 chars, lowercase, hyphen-separated, no spaces.
- Slugs are derived from the journey's intent (the journey `name` /
  goal in `pdd-to-app-journeys.md`), not from ordinal position.

**Filename vs id — related but NOT identical.** The recipe *filenames*
stay `journey-<app>[-<slug>].yaml`, and the smoke recipes use the bare
`journey-learn.yaml` / `journey-deliver.yaml` (they do NOT get an extra
`journey-` — they already start with it). The *id* is the fuller
`journey-<app>-<intent>` form (e.g. id `journey-learn-pass` →
recipe `journey-learn.yaml`; id `journey-deliver-submit` → recipe
`journey-deliver.yaml`). Filename and id share the `journey-` prefix but
are otherwise distinct — do NOT assume they must match exactly.

## Process

### Step 1: Read inputs

- `pdd-to-app-journeys.md`
- `app-summaries/learn-app-summary.md`
- `app-summaries/deliver-app-summary.md`
- The Nova blueprints (call `get_app` with each
  app id) for real form/field IDs
- The static-recipe library at `mcp/mobile/recipes/static/`

### Step 2: For each journey, decide its app + smoke flag

Map each journey from `pdd-to-app-journeys.md` to either Learn or Deliver
based on whether the journey describes assessment behavior (Learn) or
visit/delivery behavior (Deliver). Multi-stage opps may have both.

**Smoke flag rules:**
- Exactly ONE journey per app gets `is_smoke: true`
- The smoke journey is the simplest happy-path that exercises the
  app's primary submission/completion flow
- If two journeys could plausibly be the smoke, pick the one with the
  smallest `pdd_time_budget_seconds`

**Two-app coverage is REQUIRED.** Every PDD with both a Learn and a
Deliver app (every archetype except a hypothetical Learn-less mode)
MUST emit one `is_smoke: true` journey per app — Phase 6 reads BOTH
smokes to capture training-deck screenshots of each app. If
`pdd-to-app-journeys` did not produce a Learn-app journey, halt with
a structured error pointing at Phase 2 (`pdd-to-app-journeys`) rather
than writing `smoke_journeys_per_app.learn: 0` — the upstream coverage
rule (added 2026-05-18) requires the Learn smoke. The
`smoke_journeys_per_app: {learn: 1, deliver: 1}` invariant is
load-bearing for Phase 6's pre-flight; emitting `learn: 0` produces a
silent downstream halt at Phase 6 (see malaria-itn-app
run 20260517-1829 for the canonical incident).

**Deliver-smoke composition — Learn leg completes Learn, Deliver leg
resumes.** Connect gates the Deliver app behind Learn-assessment
completion (`docs/learnings/2026-05-18-connect-gates-deliver-on-learn-completion.md`).
Rather than re-walk Learn inside the Deliver recipe (the old ~80-step
monolith that was fragile and got deferred — leep 20260527 J2), the
two smoke recipes share device state within one Phase 6 dispatch:

- **`journey-learn.yaml` walks Learn to completion.** All modules
  (content form + assessment per module) through the final
  assessment-pass + sync. This both produces the Learn training
  screenshots (module list → content → quiz → completion/certificate)
  AND unlocks Deliver as a side effect. The Learn smoke is a *complete*
  walk, not a land-at-M1 thin walk.
- **`journey-deliver.yaml` resumes from the unlocked state.** It assumes
  the immediately-preceding `journey-learn` leg (same dispatch, warm
  session) completed Learn. Compose it from the static palette:
  `runFlow: connect-resume-opp.yaml` (opp list → Resume the In-Progress
  card; also backs out of the post-Learn CommCare home to the Connect
  jobs list — #618) → `runFlow: deliver-launch.yaml` (certificate/
  opp-detail → Download gate → Deliver home `viewJobCard`, ID-anchored in
  `connect-2.63.0.yaml`) → `runFlow: deliver-form-walk.yaml` (3-level
  Deliver menu: Start → module list → module row → form list → form row →
  first form question) → answer the journey's question(s) → `runFlow:
  form-submit.yaml` → `runFlow: deliver-sync.yaml`. ~14 steps, NO Learn
  duplication.

  **`deliver-sync.yaml` is MANDATORY as the last step of every Deliver
  journey (dimagi-internal/ace#1066) — a Deliver journey without it is
  not a test.** `form-submit.yaml` finalizes a plain Deliver form via its
  `nav_btn_next` auto-finalize branch, which writes to the LOCAL OUTBOX
  and asserts nothing about the server; only its score-gated branch
  (`form-nav-finish`, the Learn quiz) asserts `".*form.*sent to
  server.*"`. So a Deliver leg ending at `form-submit` proves only "the
  form walked and finalized locally" — an opp whose Deliver→Connect path
  was completely broken would still pass. Observed live on
  bednet-spot-check/20260729-1239: `status: pass`, then `Daily Visits
  0/5` and `last synced: never`.

  `deliver-sync.yaml` closes that by asserting the SERVER-DERIVED `Daily
  Visits` counter is non-zero. Note the tap on "Sync with Server" is a
  belt-and-braces upload, not the load-bearing step: CommCare sometimes
  auto-sends on finalize (in which case the sync reports "No forms sent
  to server!" — benign) and sometimes does not. The assertion is what
  makes the leg honest either way. This mirrors what jjackson/ace#897
  established for Learn: the device is not authoritative about
  completion. A Connect-side read-back is still the stronger gate and
  remains open on #1066 pending an atom.

  **Menu-row taps use `id: org.commcare.dalvik:id/row_txt`, NOT
  `text: "<label>"`.** A `text:` match hits the non-clickable action-bar
  title (same label) first in document order, so the tap is a silent
  no-op (validated live, bednet-spot-check/20260602-1345 deliver-leg pass).
  `deliver-form-walk.yaml` already encodes this; if you ever inline a
  menu-row tap instead of composing the palette recipe, use `row_txt` —
  same as the Learn side's `learn-tap-module.yaml`.

#### Registration-then-followup Deliver apps — bind `MODULE_NAME` / `FORM_NAME` (dimagi-internal/ace#1138)

**Most ACE Deliver apps are MULTI-MODULE, and that is by construction —
not an accident to design around.** One form per module is a deliberate,
load-bearing ACE pattern: Connect dedups deliver units by module slug
(`get_or_create(DeliverApp, slug)`), so two forms in one module collapse
into a SINGLE `DeliverUnit` and only one of them can ever be payable. Any
Deliver app that registers an entity and then files repeat visits against
it therefore has **at least two modules** — e.g. `CBF Registration` and
`Community Meeting Record` on Deliver app
`657a4bb7-fb2f-4a10-af43-8414707b2c43`
(spark-facilitator/20260731-0656).

`deliver-form-walk.yaml` used to tap the FIRST menu row at each level. On
a multi-module app that walks into the registration module and never
reaches the payable form — which is why that run could not author
`journey-deliver.yaml` at all and Phase 6 got zero Deliver screenshots.
**Always bind the target module (and the form, when its label differs)**,
exactly as you already do for `learn-tap-module.yaml`:

```yaml
- runFlow:
    file: deliver-form-walk.yaml
    env:
      MODULE_NAME: "Community Meeting Record"   # the PAYABLE module
      FORM_NAME: "Community Meeting Record"     # omit when it equals MODULE_NAME
      WALK_LABEL: "-deliver"                    # REQUIRED even on a lone leg (ace#1668)
```

`MODULE_NAME` / `FORM_NAME` are optional and default to the legacy
tap-first-row behavior when unbound, so single-module callers are
unchanged — but a Deliver app with
more than one module MUST bind `MODULE_NAME`, or the walk is silently
wrong rather than loudly broken. Enforced structurally by
`test/mcp/mobile/static-recipe-invariants.test.ts § positional row taps`.

**A module that holds BOTH a registration form and a followup form** (e.g.
`Groups` = `Register group` + `Add member`, group-payment-test/20261007-1700)
is walked module row → the module's own form grid → form row → case list →
form. `deliver-form-walk.yaml` handles that order (dimagi-internal/ace#2797),
but only when you bind **`FORM_NAME`** (it keeps the Level-1 positional
fallback from tapping the first form in the grid, usually the registration
form) and **`CASE_NAME`** for the followup. Never leave `FORM_NAME` unbound
on such a module.

**The payable module is the one Connect pays for, not the first one.**
Read the deliver units (`connect_list_deliver_units` /
`connect_list_payment_units`) or the Nova blueprint to pick it — do not
assume ordering.

##### Ordering: a followup form needs its case to already exist (#1138 Gap 2 — CLOSED)

When the payable form is a `followup` on a case type (the normal shape
for register-then-visit apps), reaching it forces a three-step order:

1. walk the **registration** module's form first, so a case of that type
   exists on the device;
2. **select that case** from CommCare's `EntitySelectActivity` case list;
3. only then answer the payable form.

**All three are authorable.** Step 2 is
`mcp/mobile/recipes/static/deliver-case-select.yaml`, and
`deliver-form-walk.yaml` composes it for you — you never call it
directly. Bind **`CASE_NAME`** alongside `MODULE_NAME` / `FORM_NAME` and
the walk crosses the case list on its own:

```yaml
# 1. Registration module — creates the case. No CASE_NAME (no case list).
- runFlow:
    file: deliver-form-walk.yaml
    env:
      MODULE_NAME: "CBF Registration"
      FORM_NAME: "CBF Registration"
      WALK_LABEL: "-register"                     # per-invocation frame suffix
# ...answer the registration fields, then:
- runFlow:
    file: form-submit.yaml
    env:
      SCREENSHOT_NAME_PRE_SUBMIT: "journey-deliver-reg-pre"
      SCREENSHOT_NAME_POST_SUBMIT: "journey-deliver-reg-post"

# 1b. RETURN TO THE DELIVER HOME. Not optional — see below.
- runFlow:
    when: {notVisible: {id: "${SELECTOR:deliver-home-job-card}"}}
    commands: [back, {waitForAnimationToEnd: {timeout: 3000}}]
- runFlow:
    when: {notVisible: {id: "${SELECTOR:deliver-home-job-card}"}}
    commands: [back, {waitForAnimationToEnd: {timeout: 3000}}]
- extendedWaitUntil:
    visible: {id: "${SELECTOR:deliver-home-job-card}"}
    timeout: 20000

# 2. Payable followup — CASE_NAME selects the case just registered.
- runFlow:
    file: deliver-form-walk.yaml
    env:
      MODULE_NAME: "Community Meeting Record"      # the PAYABLE module
      FORM_NAME: "Village Monitoring Record"
      CASE_NAME: "Thandiwe Banda.*"                # the case_name you entered
      WALK_LABEL: "-followup"                      # MUST differ from leg A's
```

**`WALK_LABEL` is REQUIRED at every call site — including a lone one
(ace#1651, corrected by ace#1668).** `deliver-form-walk.yaml` names three of its captures from
FIXED strings — `deliver-form-walk-module-list`, `-form-list`,
`-form-question`. Two invocations in one recipe therefore wrote the same
three filenames twice, and leg B's frames **silently overwrote leg A's**:
measured on bednet-check-2-visit/20260825-1310 (a PASSING run) the stdout
reported all three captures COMPLETED in both legs while exactly one file
of each name survived, carrying leg B's `takenAt`. The registration
evidence the training deck and `app-ux-eval` read was destroyed, and if
leg B fails it destroys precisely the frames an operator needs to see how
the case got created.

Bind a short `[a-z0-9-]` slug **including the leading separator**, and a
DIFFERENT one per call site.

**Do not omit it on a single-invocation walk.** The #1651 fix said you
could, on the premise that an unbound `${WALK_LABEL}` substitutes to the
empty string and keeps byte-identical names. That premise is false:
Maestro evaluates `${...}` in a JS engine, so an unbound variable
stringifies to the literal text `undefined`. The very next run's Deliver
leg wrote `deliver-form-walk-module-listundefined.png`,
`-form-listundefined.png`, `-form-questionundefined.png` and
`deliver-form-walk-module-row-Household poverty surveyundefined.png`
(hh-poverty-targeting/20260824-1404) — names that reach the screenshot
manifest, the training deck and the FLW guide, where they read as a
defect in the deliverable (ace#1668). And a default inside the palette's
own `env:` block is NOT the fix — a subflow `env:` OVERRIDES the caller's
`runFlow.env` in Maestro (ace#1033), so it would force both legs to the
same value and silently restore the #1651 overwrite.

*Enforced two ways, both run by `mobile_validate_recipe`:*
`lintRecipeText`'s `runFlow-unbound-screenshot-name` rule fails **any**
call site that omits `WALK_LABEL` (or binds it empty), and
`repeat-palette-invocation-without-discriminator` fails a recipe that
invokes the palette twice with a duplicated one.
`test/mcp/mobile/static-recipe-invariants.test.ts § deliver-form-walk
per-invocation frame names` pins the palette side, including the literal
`undefined` expansion that #1651's own test suite had assumed away.

**Step 1b exists because the two recipes' own contracts do not meet
(ace#1191).** `deliver-form-walk.yaml`'s header declares
*"Pre-state: Deliver home (deliver-home-job-card / viewJobCard visible)"* and
its first action taps `Start`; `form-submit.yaml`'s header declares
*"Post-state: depends on the form … Deliver forms (TBD)"*. `deliver-sync.yaml`
records the real behaviour in passing — *"form-submit returns to the form list
(or the module list) rather than the app home"* — which is exactly why
deliver-sync itself opens with four guarded `back` steps (a case-bound Deliver
form sits one level deeper — ace#1494).

Without 1b the second leg starts inside a form. Live on
`spark-facilitator/20260813-2126` the Deliver smoke walked leg A, then died at
the inter-leg back-navigation on CommCare's unmapped **"Exit Form?"** dialog
(ace#1290) — having already taken its POST_SUBMIT screenshot and reported
success.

The guarded form above is a **no-op when the device is already home**, and it
mirrors `deliver-sync.yaml`'s proven pattern rather than inventing a new one.
It is inlined rather than shipped as a palette recipe because a palette
recipe must be proven on a live device before it merges, and the
`deliver-home-reentry.yaml` entry is still pending that validation (#1191).

*Enforced:* `test/mcp/mobile/static-recipe-invariants.test.ts § two-leg Deliver
chain continuity` runs `checkChainContinuity` (`lib/recipe-state-contract.ts`)
over the real palette files and fails if the un-bridged sequence ever starts
looking connected.

**`CASE_NAME` must be the value you actually typed into the registration
form's `case_name` field** — it is what renders in the case list's first
column. Pass it as a literal prefix plus `.*` (Maestro `text:` is a
FULL-match regex and case-list cells are routinely truncated — and on any
app built before 2026-08-14, language-stacked as well). Omit it on a followup and the walk fails loud on the case
list rather than silently picking a row.

**Match an id-mapping column's rendered label with surrounding-whitespace
tolerance** (ace#2692). A Nova `id-mapping` case-list column compiles in HQ
to `replace(join(' ', if(selected(...), label, ''), ...), '\s+', ' ')`, which
collapses but never trims, so every value but the first renders with a
leading space and every value but the last with a trailing one — on
`spark-facilitator/20261004-1706` the device showed `"Step 1: Our Partnership "`
and `" Step 2: Community Dynamics, Governance &amp; Leadership "` for clean
blueprint labels. A `text:` exact match on such a cell fails. Wrap the label
as ` *<label> *` (or `.*<label>.*`), never the bare label, in any `tapOn`,
`assertVisible` or `CASE_NAME`-style match on an id-mapping column.

Two things worth knowing, both live-established on 2.63.2 and both
already handled inside the palette — do not re-derive them:

- CommCare collects the **case before the form**: module row → case list
  → case detail → CONTINUE → form list → form. The detail screen is a
  real screen with its own CONTINUE button, not a dialog.
- The case list's **column headers reuse the row cells' resource-id**,
  and the toolbar carries the module name, so a case tap is scoped to the
  list container. Never hand-roll a case tap; compose the palette.

**Do NOT substitute the registration form for the payable one** and call
the journey a Deliver smoke — that produces a green journey that never
exercises the payable unit, which is the entire thing Phase 6's Deliver
leg exists to prove. If the payable form genuinely cannot be reached,
halt with a `[BLOCKER]` naming what stopped the walk; do not downgrade
the target.

State the warm-state dependency in `journey-deliver.yaml`'s header
comment: it is NOT independently cold-runnable; runners execute
journey-learn → journey-deliver in order.

**The `composition_status` escape stays banned.** Do NOT write
`composition_status: <anything>` on any `is_smoke: true` journey — its
presence is a contract violation (it self-declares a known-broken
recipe). With the Learn-completes / Deliver-resumes split, the common
case IS composable, so the old "monolith or BLOCKER" binary is gone.

Halt with a `[BLOCKER]` only when the structure genuinely can't be
composed — e.g. the Learn blueprint is missing the modules the walk
needs, or `deliver-launch.yaml`'s anchors don't resolve against the
active selector map. A `journey-deliver.yaml` that re-walks Learn
(`learn-launch` or ≥2 `learn-tap-module`) is rejected by the
`deliver-smoke-rewalks-learn` recipe-sanity check (Step 3.4-adjacent) —
re-compose it as resume-only.

Caught in vivo on malaria-itn-app run 20260517-1829 (the second time —
PR #354 fixed the Phase 6 pre-flight; the composition contract change
here closes the upstream Phase 3 escape that produced the legacy recipe
in the first place). With the split model, composition is the default
path; Defer only by halting with a `[BLOCKER]`; never by writing a
known-broken recipe.

### Step 3: For the SMOKE journeys, compose the Maestro recipe

**Compose recipes ONLY for the `is_smoke: true` journeys** (the two
smokes: `journey-learn-pass` → `journey-learn.yaml`,
`journey-deliver-submit` → `journey-deliver.yaml`). For every non-smoke
(deep) journey, do NOT author a recipe file at Phase 3 — set the catalog
entry's `recipe: deferred` instead (see § Products and Step 4). The
composition rules below apply to the smoke recipes; `/ace:qa-deep` reuses
these exact rules to generate the deferred deep recipes on demand.

**Groups are field-lists — one screen, NOT one screen per question.**
A Nova `kind: group` compiles to a CommCare **field-list**: every child
(labels *and* questions) renders on ONE scrollable screen. Composing a
per-child `tapOn option → nav_btn_next` walk inside a group is
structurally wrong — the first advance fires while the screen's other
required children are still unanswered, so the form stalls on
`warning_root` ("Sorry, this response is required!"), and later options
may sit above/below the fold. Read `nova_get_form` and check for
`children[]` before composing. For each group emit a **single-screen
walk**:

1. `takeScreenshot` on entering the screen.
2. Per select child: **scroll to the OPTION, scoped below the question
   label, then tap it with the same anchor** (ace#2186). The scroll target
   is the element you are about to tap — never only its question label.

   ```yaml
   # every select question in the group, whatever its position
   # (a) bring the question into view — never centred
   - scrollUntilVisible:
       element:
         text: "[\\s\\S]*<question label>[\\s\\S]*"
       direction: DOWN
       speed: 15
       timeout: 20000
       visibilityPercentage: 30
       centerElement: false
   # (b) THE GUARD: scroll to the option itself, scoped below that label
   - scrollUntilVisible:
       element:
         text: "<literal option label>"
         below:
           text: "[\\s\\S]*<question label>[\\s\\S]*"
       direction: DOWN
       speed: 15
       timeout: 20000
       visibilityPercentage: 100
       centerElement: false
   - tapOn:
       text: "<literal option label>"
       below:
         text: "[\\s\\S]*<same question label>[\\s\\S]*"
   ```

   - **(a) is positioning, (b) is the guard.** (a) alone reports COMPLETED
     with the label flush at the pane bottom and its options below the
     fold — that is this whole defect. (b) is what the tap needs.
   - **`below:` the question label** keeps a shared option label (`Yes`,
     `A. Yes`) on THIS question rather than the first match on screen —
     the scroll and the tap address the same region (scope parity, below).
   - **`visibilityPercentage: 100`** stops the scroll only once the whole
     radio row is on screen, not a sliver of it at the pane edge.
   - **`centerElement: false`** — centring is what evicts things. Centre the
     label and its options fall off the bottom; centre the option and, on a
     long option list, its label falls off the top and the `below:` anchor
     resolves to nothing.

   **Why not "scroll to the label, choose `centerElement` by position"
   (the retired ace#1814 rule).** Whether a question's options are on
   screen when its turn comes is a function of cumulative pixel layout —
   label wrap length, the group header, how much the earlier questions
   consumed — not of the question's ordinal position. A label scroll
   reports COMPLETED as soon as the label is visible, which can be flush at
   the pane bottom with every option below the fold; `tapOn ... below:`
   then dies `selector-not-found`. The by-position table was generalised
   from one run's layout (`hh-poverty-targeting/20260828-0702`) and failed
   on the near-identical PPI group of a sibling programme:
   `poverty-graduation/20260905-1345` (dispatch `1788809949430-fyk66c`)
   died at MILK — question **3 of 4**, `centerElement: false` exactly as
   the table said — with the MILK label clipped to 39px at the bottom edge
   and no option in the hierarchy. The same shape recurred on
   `smallholder-seasonal/20261012-1549` ("Is there a dry-season cropping
   cycle…", a middle question of a 6-question group).

   **Device evidence for the option scroll.** Both runs passed once each
   option tap was preceded by a scroll to the option itself, scoped below
   its label: `poverty-graduation` (dispatch `1788810583478-glxovg`, 7
   label/option pairs rewritten, full Deliver leg passed) and
   `smallholder-seasonal/20261012-1549` (all 21 `below:`-scoped option
   taps rewritten; Community walk, Dwelling screening and Census and PPI
   survey walked to `status: pass`). In both, the option scroll was
   ADDED after a `centerElement: false` label scroll — exactly the (a)+(b)
   pair above. Dropping (a) and keeping only (b) has not been separately
   re-run on a device, so keep both.

   **Do not stack the § Quiz option-centring guard (ace#1070,
   `centerElement: true`) on a `below:`-anchored tap.** Each is sanctioned
   on its own, but together they are self-defeating for any option list
   long enough that the option cannot be centred without evicting its
   question label: live, centring `Chikwawa` (option 7 of 28) pushed
   "District" off the top and `Tap on "Chikwawa", Below "…District…"`
   failed with `Chikwawa` on screen. The option scroll above, with
   `centerElement: false`, is the field-list form.

   **`speed` is NOT the lever here** — re-running the original overshoot
   at `speed: 15` with the label-centring rule failed at the identical
   step with an identical dump (ace#1814). Do not re-propose tuning it for
   this class.

   *Enforced:* `unguarded-option-tap-below-long-label` in
   `mcp/mobile/recipe-sanity-probe.ts` accepts only a preceding
   `scrollUntilVisible` whose matchers reach the OPTION — a label-only
   scroll does not clear it (pinned in
   `test/mcp/mobile/recipe-sanity-probe.test.ts`, ace#2186).

   **A guard must carry the same scope as the tap it protects
   (ace#2426).** If you emit a `when: notVisible` pre-scroll in front of an
   option tap at all, its condition AND its `scrollUntilVisible` element
   must carry the **identical `below:` anchor** the tap carries. **A global
   guard cannot protect a scoped tap.**

   ```yaml
   # WRONG — global guard, global scroll, scoped tap
   - runFlow:
       when:
         notVisible:
           text: "No"                                     # <- whole screen
       commands:
         - scrollUntilVisible:
             element:
               text: "No"                                 # <- whole screen
   - tapOn:
       text: "No"
       below:
         text: "[\\s\\S]*<this question>[\\s\\S]*"        # <- one region

   # RIGHT — all three address the same region
   - runFlow:
       when:
         notVisible:
           text: "No"
           below:
             text: "[\\s\\S]*<this question>[\\s\\S]*"
       commands:
         - scrollUntilVisible:
             element:
               text: "No"
               below:
                 text: "[\\s\\S]*<this question>[\\s\\S]*"
   - tapOn:
       text: "No"
       below:
         text: "[\\s\\S]*<this question>[\\s\\S]*"
   ```

   **Why, from Maestro's own model rather than from one device run.** A
   `when:` condition owns its OWN element selector (`Condition.visible` /
   `Condition.notVisible`), `below` is a property OF a selector, and it
   compiles to a `Filters.below(...)` stage intersected into that
   selector's filter chain — i.e. it strictly NARROWS the candidate set.
   So the global guard asks *"is there no `No` anywhere on screen"* while
   the tap needs *"a `No` below MY question"*. In a field-list holding four
   identically-labelled Yes/No questions a bare `No` is essentially always
   visible somewhere, so the guard is a runtime **no-op**, the scroll never
   fires, and the tap dies the instant its own options fall below the fold
   — which is the "anchor visible, options not" state ace#1299 § 2 calls
   the more important half of the bug.

   Live: `poverty-graduation/20260915-1518` failed
   `Element not found: Text matching regex: No, Below: ...MILK...` on the
   `g_food7` field-list, with the MILK label visible at the very bottom
   ([42,2214][1038,2337] on 1080x2400) and BREAD's `No` visible above it at
   [42,1121][1038,1205]. Scoping all 13 guard/scroll pairs took the leg
   from `selector-not-found` to `pass` — 43 screenshots, 0 failures, all 14
   screens.

   This does **not** touch § Quiz / required-input answer-tap rule item 2,
   whose guard is global because its tap is too (one question per screen,
   nothing to scope against). The rule is scope PARITY, not "always
   scope": *the guard may never evaluate a wider region than the tap it
   protects.* *Enforced:* `option-tap-guard-is-unscoped` in
   `mcp/mobile/recipe-sanity-probe.ts`, which fires only on a
   `below:`-scoped tap sitting behind a global guard.
3. Per label-less EditText child: **`below:` anchored on the question
   label is NOT reliable and is inert whenever the question has a hint
   (ace#1299).** The calibrated layout order is

       label TextView  ->  optional hint TextView  ->  EditText

   so `below: <question label>` selects the **hint**, and tapping a
   TextView does nothing. The tap reports success, focus never moves, and
   every subsequent `inputText` appends into whichever field was already
   focused. Live on `spark-facilitator/20260813-2126` that produced
   `cbf_name = "Thandiwe Banda0991234567"` with `phone_number` empty and
   required — silent data corruption, not a visible failure.

   The idiom appears to work on questions WITHOUT a hint, which is why it
   was recorded as live-validated: the failure is per-question, not
   per-form.

   Two live facts to compose against instead (CommCare 2.63.2 /
   `ACE_Pixel_API_34`, ui-dump 2026-08-14):

   - **CommCare AUTOFOCUSES the first input of a field-list at form
     open** — `focused=true` with zero taps — so the first value needs no
     tap at all, just `inputText`.
   - **The answer EditText carries NO resource-id** on this build.
     `org.odk.collect.android:id/answer_text` (the old
     `form-question-input` guess) does not exist; match by class
     (`android.widget.EditText`) and position.

   **The focus anchor is the element immediately above the `EditText` —
   the field's `hint` when it has one, the question label when it does
   not** (ace#1299, follow-up comment: Nova's authoritative `hint` map
   diffed against all 14 inputs of both Deliver forms on
   `spark-facilitator/20260813-2126`; 3 anchors were wrong and all 3 were
   hint-carrying fields anchored on their label, which is why this read as
   intermittent rather than systematic).

   So for every input the autofocus does NOT cover — i.e. every input
   after the first on a field-list — emit (validated on-device, ace#1299:
   an isolated probe on that live registration screen landed `cbf_name` =
   `'PROBE-NAME'` and `phone_number` = `'0991234567'` in their OWN fields,
   where the label-anchored idiom had put both into one):

   ```yaml
   - scrollUntilVisible:
       element:
         text: "[\\s\\S]*<hint if present, else question label>[\\s\\S]*"
       direction: DOWN
       speed: 30
       timeout: 20000
       visibilityPercentage: 60
       centerElement: true
   - tapOn:
       below:
         text: "[\\s\\S]*<same anchor>[\\s\\S]*"
   - eraseText
   - inputText: "<value>"
   - hideKeyboard
   ```

   **Guarded vs unconditional — the discriminator is whether the anchor IS
   the tap target.** Both shapes are correct, in different places, and
   picking by habit rather than by this test reintroduces one of the two
   bugs (ace#1070, ace#1299):

   - **Anchor IS the tap target** (a unique option label, a named button)
     → keep the `when: notVisible` **guarded** scroll of § Quiz /
     required-input answer-tap rule. ace#1070 stands: an unconditional
     scroll on an option that already fits reads as backward form
     navigation and walks the flow out of the form.
   - **Anchor is a DIFFERENT element from the tap target** (an `EditText`
     reached via the hint above it) → **unconditional** centring scroll, as
     in the snippet above. (A field-list OPTION is not this case: scroll to
     the option itself, scoped below its label — item 2, ace#2186.) The failure mode there is "anchor visible, its
     `EditText` still below the fold", which `notVisible: <anchor>` is
     structurally blind to — so the guard suppresses the one scroll that
     was needed. That half affected all 14 inputs, not just the 3 with
     wrong anchors (ace#1299).

   `speed: 30`, not 80: at 80 the centring scroll overshot a ~300px radio
   band and halted the leg (ace#1299).

   Index-based anchoring within the field-list is still **uncalibrated** —
   use the hint/label anchor above, which is proven (ace#1299); do not
   guess an index.
4. Exactly **ONE** trailing form-advance, after every REQUIRED child is
   answered.

Two matcher traps on that screen:

- **Regex metacharacters break Maestro's full-match `text:`.** Question
  labels routinely contain parentheses. Compose the matcher as
  `"<literal prefix>.*"` rather than the full label.
- **Option matchers use the RENDERED label, not the Nova label (ace#1689,
  ace#2876).** CommCare renders every choice label through its
  `form="markdown"` twin, so a label that starts with a markdown block
  marker loses it on-device: Nova's `25. At most 25 surveys a day are paid`
  is a RadioButton reading `At most 25 surveys a day are paid`
  (smallholder-seasonal/20261012-1549, Learn Module 3 q4). Before you write
  any `text:` for an option, pass the Nova label through
  `renderMarkdownLabel(label).rendered` (`lib/choice-label-integrity.ts`)
  and compose the matcher from THAT string (still replacing regex
  metacharacters with `.`). *Enforced:* `recipe-sanity-probe` fails
  `markdown-eaten-option-matcher` on a matcher that matches the authored
  label but not the rendered one — supply each field's `options` in Step
  2.6's `fields` or the check cannot run.
- **N identical option labels are not text-matchable.** A field-list
  carrying nine `"Option A"`s cannot be disambiguated by text. Leave
  OPTIONAL children unanswered until the labels are distinct, and say so
  in the recipe header.

`recipe-sanity-probe` enforces this statically as
`group-field-list-per-question-walk` when Step 2.6's caller supplies
`fields` (ace#862).

**Both halves of item 3 are statically enforced too** (ace#1554):

- `input-anchor-skips-hint` — a focus tap anchored on the QUESTION LABEL
  of a field that carries a `hint`. Hint-gated: it reads only fields that
  positively carry a hint, so a caller that did not supply `hint` gets a
  no-op, never an assumed "no hint". Supply `hint` alongside `label` in
  Step 2.6's `fields` for it to run at all.
- `input-focus-scroll-is-guarded` — a `when: notVisible: <anchor>` wrapper
  around the centring scroll for a `tapOn: below:` + `inputText` pair.
  This one needs no Nova data; it is the guarded-vs-unconditional
  discriminator below, made non-optional.
- `option-tap-guard-is-unscoped` — a GLOBAL `when: notVisible: "<option>"`
  guard in front of a `below:`-SCOPED option tap. The static enforcement of
  § A guard must carry the same scope as the tap it protects, below. Needs
  no Nova data either.

**Every `- inputText` is immediately preceded by `- eraseText`** — on a
field-list, a standalone question, anywhere. Maestro's `inputText`
*appends at the cursor*; it does not replace, so a field already carrying
a Nova casedb preload, an XForm default, or a stray character receives the
two values concatenated. Live: `spark-facilitator/20260828-0703` typed
`40` into `hh_represented_at_the_meeting`, submitted `140`, and the form's
cross-field constraint refused to advance — the leg then died two screens
later on an unrelated scroll, reading as a selector fault it was not. And
wherever it does *not* happen to trip a constraint the corruption is
SILENT: the leg reports `pass` on wrong data. A redundant erase on an
empty field is a runtime no-op, so there is never a reason to omit it.
Enforced statically as `input-without-erase` (ace#1844) — needs no Nova
data, so it runs on every recipe.

**Anchor every shared option label.** The probe attributes a step to a
group by the strings the step selects on, and a bare `tapOn: text: "Yes"`
names no screen — on the normal shape (a consumption block plus an assets
block, both Yes/No) it is a child of two groups at once. Since ace#1548 an
ambiguous matcher attributes to NOTHING rather than to whichever group
enumerates first, so the check simply goes quiet on unanchored option taps.
Keep the `below:` anchor naming the question
(`"[\\s\\S]*<question label>[\\s\\S]*"` — two backslashes, as in the
snippet above; `\s` is not a legal escape in a YAML double-quoted scalar)
on every option tap — it is what makes the check able to see your screen
at all.

Compose each smoke recipe using the static palette pattern (one Maestro
step per UI interaction, with `${SELECTOR:logical-name}`
placeholders resolved at write time, and `takeScreenshot` calls
between major form sections):

- Recipes are named by app + intent, not journey-id: `journey-learn.yaml` / `journey-deliver.yaml` for the smokes, `journey-<app>-<slug>.yaml` for the (lazily-generated) deep recipes. The journey `id` (a `journey-`-prefixed meaningful kebab-case slug like `journey-learn-pass` / `journey-deliver-submit` — see § Journey id convention) lives in `app-test-cases.yaml`, not the filename.
- Each journey's recipe MUST include a final `takeScreenshot: "<recipe-base>-final"` (e.g. `journey-learn-final`, `journey-deliver-final`) for the deep UX judge to grade
- Resolve any `${SELECTOR:logical-name}` placeholders via
  `mobile_resolve_selectors` against the current APK selector map
  before validating (see Step 3.4 below — selector-resolution is a
  fail-loud gate, not just a substitution pass)
- Validate via `mobile_validate_recipe` before writing.
  *Enforced:* since ace#1690, `mobile_run_recipe` runs the same linter on
  every recipe it dispatches and refuses a failing one with
  `RECIPE_LINT_FAILED`. Calling `mobile_validate_recipe` first is still
  right — it fails in one cheap static call instead of at device dispatch —
  but skipping it no longer lets a malformed recipe reach a device

#### The accepted step-key dialect (ace#1008)

`mobile_validate_recipe` rejects any step key outside
`ALLOWED_STEP_KEYS` in `mcp/mobile/backends/maestro.ts`. **That list is
the source of truth — grep it rather than guessing**, and note that
**no step is deliberately banned for agent-authored recipes.** The
allowlist exists to catch typos and Maestro-version drift, not to hold
journey recipes to a narrower dialect than the shipped static palette.

The invariant (pinned by
`test/mcp/mobile/palette-step-allowlist.test.ts`): the allowlist is a
superset of every step key used under `mcp/mobile/recipes/static/`.
Palette files never pass through the validator, so before ace#1008 the
two silently diverged — `scrollUntilVisible` (used by
`connect-resume-opp.yaml` and `connect-claim-opp.yaml`) was rejected in
agent-authored recipes, forcing authors to either drop legitimate
scroll-into-view behaviour or ship an unvalidated recipe. If a
validator rejection ever looks like that again — the palette uses the
step, the validator refuses it — **that is an ACE defect: file it and
add the key**, don't work around it.

#### Maestro inputText: scalar vs mapping form

`inputText` has two valid shapes — pick the right one based on
whether you need any options:

```yaml
# Scalar form — text only, no options
- inputText: "Apcolite Stores"

# Mapping form — REQUIRED when you need any inputText option
# (optional, label, id, point, etc.)
- inputText:
    text: "Apcolite Stores"
    optional: true
```

The combination that **does not parse** is the scalar form with
a sibling option key under the same list item:

```yaml
- inputText: "Apcolite Stores"
    optional: true            # ← Maestro rejects this at parse time
```

This is invalid YAML — the `-` opens a list item that's *both* a
scalar (`inputText: "..."`) and a mapping (`optional: true`).
Maestro's parser surfaces it as:
`expected <block end>, but found '<block mapping start>'`.

The same rule applies to every Maestro command that has both a
scalar and a mapping form (`tapOn`, `assertVisible`,
`extendedWaitUntil`, etc.): use the mapping form whenever you need
*any* option beyond the bare value.

Caught in vivo on leep Phase 6 attempt 8 (2026-05-12) — the Learn
smoke recipe (`journey-learn.yaml`, id `journey-learn-pass`)
emitted the broken sibling form, Phase 6 halted, the cloud
emulator stack returned a full structured error envelope with the
Maestro parse-error frame which named this exact pattern.

#### Entry-point template — Connect-integrated flow

ACE-Phase-5 recipes drive a CommCare install that's **Connect-
integrated**, not standalone. The post-`launchApp` surface on
CommCare 2.62.0 is `screen_first_start_main` (Welcome to CommCare)
with buttons like `GO TO CONNECT MENU`, `Scan Barcode`,
`Enter Code` — there is **no app-name tile** to tap. Apps reach
the device via Connect's claim → Start workflow.

The mistake to avoid (caught on leep Phase 5 attempt 10):

```yaml
# WRONG — assumes the standalone-CommCare model, which doesn't exist
- launchApp
- tapOn:
    text: "ACE - LEEP Paint Surveillance - Deliver"   # ← no such tile
```

Right pattern: chain the static palette to land at the per-journey
form, then add journey-specific steps:

```yaml
# RIGHT — composes the static palette
appId: org.commcare.dalvik
---
# (a) Connect login, navigates to Opportunities home
- runFlow:
    file: connect-login.yaml
# (b) For each opp's first journey, claim+Start the opp once
- runFlow:
    file: connect-claim-opp.yaml
    env:
      OPP_NAME: ${OPP_NAME}
# (c) For Learn journeys: learn-launch.yaml lands on the Learn suite root.
#     Walk all Learn modules to completion (all content forms + assessments)
#     through the final assessment-pass + sync. This is a complete walk,
#     not a thin land-at-M1 walk — it both produces Learn screenshots and
#     unlocks the Deliver app as a side effect.
#
#     For Deliver journeys: `journey-deliver.yaml` resumes from the
#     unlocked state (warm session, journey-learn leg just completed).
#     Do NOT re-walk Learn inside the Deliver recipe — use the split:
#       connect-resume-opp.yaml  (opp-list → tap Resume → cert/opp-detail)
#       runFlow: deliver-launch.yaml  (cert → Download gate → Deliver home)
#       … first Deliver module + form screenshot
#     The Deliver recipe is NOT independently cold-runnable; state the
#     warm-state dependency in the YAML header comment.
- runFlow:
    file: learn-launch.yaml
# ... journey-specific module/form steps below, using live labels
#     from Nova get_form (see "Use live labels" section below)
- takeScreenshot: "journey-learn-final"
```

**MENU ANCHORS ARE DISPLAY-MODE-AGNOSTIC — never hardcode a container id (dimagi-internal/ace#1127).** CommCare renders the same MenuActivity rows (`row_img` + `row_txt`) inside a DIFFERENT container depending on the app's menu display setting: `screen_suite_menu_list` (ListView, list mode) or `grid_menu_grid` (GridView, grid mode). Phase 3 `app-hq-settings` applies **grid** display app-wide (#1082/PR #1100), so grid is the live shape for every ACE opp. Always reference `${SELECTOR:learn-suite-menu}` / `${SELECTOR:deliver-suite-menu}`, whose map values are regex alternations accepting either container (Maestro matches `id:` as a regex). Writing a raw `id: "org.commcare.dalvik:id/screen_suite_menu_list"` into a generated recipe is how the ENTIRE palette became unexecutable on 2026-07-31 (bednet-spot-check/20260731-1353: Learn halted at `learn-launch.yaml`, Deliver walled identically, Phase 6 `verdict: blocked`). Prose below that names `screen_suite_menu_list` is describing the original list-mode incident, not prescribing the anchor. Enforced by `test/mcp/mobile/static-recipe-invariants.test.ts § menu-container anchors`.

The static palette lives at `mcp/mobile/recipes/static/`:
- `connect-login.yaml` — splash → nav drawer → Sign In → Opportunities home
- `connect-claim-opp.yaml` — opp-list → tap opp's View Opportunity button (scoped by `below: text`) → Start → handoff to StandardHomeActivity
- `learn-launch.yaml` — post-claim StandardHomeActivity (Start tile) → MenuActivity suite root
- `learn-tap-module.yaml` — MenuActivity row tap (generic — handles ANY level of the 3-level suite tree)
- `form-advance.yaml` — `nav_btn_next` ImageButton tap (NOT text-match "Next" — see atlas §7). **Every `runFlow` of this palette MUST pass `SCREENSHOT_NAME`** — see § Screenshot names are caller-bound.
- `form-submit.yaml` — branched: explicit Submit button if visible, otherwise auto-finalize via `nav_btn_next`. **Every `runFlow` of this palette MUST pass `SCREENSHOT_NAME_PRE_SUBMIT` + `SCREENSHOT_NAME_POST_SUBMIT` env params** with per-journey names (e.g. `deliver-final-review` / `deliver-finalized`) — see § Screenshot names are caller-bound. **Never name the POST_SUBMIT frame `*-confirmation`**: on a plain Deliver form it is the form list (no toast — finalize writes to the local outbox, ace#1066), and captions trust the name (ace#2894). The submission evidence is `deliver-sync.yaml`'s post-sync `Daily Visits N/M` counter. There are NO palette-side fallbacks: the `env:` defaults added for ace#852 turned out to SHADOW the caller's names and were removed in ace#1033.
- `content-form-finish.yaml` — **the Learn CONTENT-form finalize, home-grid variant.** A bounded multi-screen advance loop that taps `nav_btn_next` until the form auto-finalizes back to StandardHomeActivity, exits on the `learn-home-start-tile` home anchor (NOT the suite menu), handles the score-gated two-screen FINISH, and asserts the home grid post-finalize. Correct ONLY on a multi-module Learn app whose forms are `post_submit: module`; on `post_submit: previous` (Nova's default) the finalize lands on the module form list and this recipe's terminal home assert cannot fire (dimagi-internal/ace#1566). Use it for label-only content/lesson forms — NOT for required-input quizzes (those still need per-field answer-taps + `form-advance` + `form-submit`). Requires `SCREENSHOT_NAME`. See § Multi-screen content forms below.
- `learn-suite-reentry.yaml` — **the between-modules suite re-entry, home-grid variant.** Tap the home Start tile → wait `screen_suite_menu_list`. Correct ONLY when the form is `post_submit: module`, which finalizes to StandardHomeActivity. Same surface contract as `learn-launch.yaml` (the first, post-claim suite entry); split out under a distinct name to document the between-modules intent at the call site.
- `learn-suite-reentry-from-module.yaml` — **the between-modules suite re-entry, form-list variant.** `back` → wait `screen_suite_menu_list`. Correct when the form is `post_submit: previous` (**Nova's default**) AND the form's own module renders a form list to come back to. Composing the home-grid variant here hangs the walk for 30s on a "Start" tile that never renders (dimagi-internal/ace#1071); firing this one from the suite root instead — which is where `previous` lands for a module CommCare auto-skipped — walks back out of the suite (dimagi-internal/ace#1633), so **always call it guarded on the next module's row**. Both are per-FORM decisions: see § Suite re-entry between modules.
- **Pick between those two PER FORM, from `get_form().post_submit` plus the owning module's form count** — see § Suite re-entry between modules below for the table, the per-form rule (dimagi-internal/ace#1633), the guarded call site, and the reason the two recipes cannot be merged into one. **NOTE:** both are for MULTI-module Learn apps. For a **single-module** Learn app (one CommCare module holding all forms), forms finalize back to the suite list — use `content-form-finish-to-suite.yaml` and OMIT the re-entry step entirely. See § SINGLE-MODULE Learn app below (jjackson/ace#894).
- `content-form-finish-to-suite.yaml` — **the Learn CONTENT-form finalize, menu variant.** `content-form-finish.yaml` re-keyed on `${SELECTOR:learn-suite-menu}` (a display-mode-agnostic alternation that matches the suite root AND a module's own form list, #1127) instead of the home tile. Correct for a **single-module** Learn app (one CommCare module holding all forms — proven live hh-poverty-targeting/20260722-1341, jjackson/ace#894) AND for a **multi-module** app whose forms are `post_submit: previous` (dimagi-internal/ace#1566). Requires `SCREENSHOT_NAME`. See § Multi-screen content forms and § SINGLE-MODULE Learn app below.
- `connect-resume-opp.yaml` — opp-list → scroll to the target opp's In-Progress card → tap Resume → lands on the certificate/opp-detail surface (atlas § 8) that `deliver-launch.yaml` expects. Pre-state: Connect opp-list visible, opp already Learn-in-progress or complete. Warm-session only (journey-learn leg completed Learn in this dispatch). Matches the tile on **`OPP_RUN_ID`** (`text: ".*${OPP_RUN_ID}.*"`), not `OPP_NAME` — the recipe header is the contract, don't restate its parameters here (ace#974).
- `deliver-launch.yaml` — post-Learn-complete certificate (atlas § 8) → tap VIEW OPPORTUNITY DETAILS → Download Delivery gate (§ 9) → tap DOWNLOAD → Deliver-mode StandardHomeActivity (§ 10) anchored on `id/viewJobCard`. All surfaces ID-anchored (verified 2026-05-26 against bednet J2 dumps; no coordinate fallbacks). Chain after `connect-resume-opp.yaml` in the Deliver smoke recipe.

**CRITICAL — Learn-app navigation is 2 menu levels deep.** After `learn-launch.yaml` lands you on the module list (atlas §6a), reaching a form means drilling two levels:

1. Tap module-list row (e.g. `"1. Survey Background & Adulteration Basics"`) → drills 6a → 6b (form list).
2. Open the form-list row (e.g. `"Background & Adulteration Basics"` for the lesson, or `"Module 1 Quiz"` for the quiz) → launches FormEntryActivity (6b → §7).

**Pass BOTH `MODULE_NAME` and `FORM_NAME` to a SINGLE `learn-tap-module` invocation.** `learn-tap-module` is robust to all three landing states in one call:

- **Auto-skip** (module-name != form-name, CommCare skips the one-row list) → lands directly on the form; no further action.
- **Same-name intermediate list** (module-name == form-name) → Branch B taps the one row by `${MODULE_NAME}` to open the form.
- **Distinct-form-name intermediate list** (module-name != form-name, CommCare does NOT auto-skip) → Branch C taps the form row by `${FORM_NAME}` to open the form.

The single-call form is the canonical pattern. (The legacy two-call drill — one `learn-tap-module` with the module name, then a second with the form name — still works because `FORM_NAME` is optional, but prefer the single call: it removes the authoring guess about whether CommCare will auto-skip, which was the malaria-itn-app/20260528-1607 Phase 6 halt class.)

Earlier-authored recipes that fired only ONE module-level `learn-tap-module` (no `FORM_NAME`) and then immediately tapped a form-internal option landed on the form LIST, not the form — the form-internal `tapOn` then found no target and hard-failed with `selector-not-found`. This is exactly the malaria-itn-app/20260528-1607 halt: module "Visit Purpose & Ethics" → form "Purpose, Consent & Do-No-Harm" (distinct, descriptive names — good authoring), CommCare left the device on the one-row form-list, and the recipe assumed it was already inside the form. Passing `FORM_NAME` in the single call (Branch C) opens the form structurally. (Also verified live on turmeric run 20260513-2243 retry #4 for the no-second-tap class — see atlas §6.)

For the canonical Learn-app smoke recipe template:

```yaml
- runFlow:
    file: learn-launch.yaml
# Drill from module list to the target form in ONE call — learn-tap-module
# opens the form whether CommCare auto-skips, shows a same-name one-row
# list, or shows a distinct-form-name one-row list.
- runFlow:
    file: learn-tap-module.yaml
    env:
      MODULE_NAME: "1. Survey Background & Adulteration Basics"  # the module-list row
      FORM_NAME: "Background & Adulteration Basics"              # the form (lesson) row, or "Module 1 Quiz"
# Now on FormEntryActivity for that form.
- tapOn:
    ${SELECTOR:form-nav-next}
# ... rest of form-question handling
```

Read live module + form names from Nova's `get_form` per the "Use live labels" section below — the pre-claim teaser at `tv_learn_modules_list` lists module names verbatim, but form names inside each module are only visible via Nova. `FORM_NAME` MUST be the form's live `label` from `get_form` (verbatim), not the PDD-brief name.

##### Multi-screen content forms — pick the finalize variant from `post_submit`

**Learn CONTENT forms are paginated, multi-screen, and label-only — walk
each one with a `content-form-finish*` recipe, NOT a single
`form-submit.yaml`.**
A Learn content/lesson form (e.g. "Program Orientation", "Identifying RDTs",
"Photo Protocol") is a multi-screen form: the first screen shows BOTH
`nav_btn_prev` and `nav_btn_next` and the progress bar is not full. A single
`form-submit.yaml` (one `nav_btn_next` tap) advances exactly ONE page and
then looks for FINISH — so it **stalls on page 2 of the first content form**,
and the next `learn-tap-module` hard-fails asserting the suite menu.
This was the malaria-rdt/20260601-0929 Phase 6 Learn-walk blocker
(jjackson/ace#646).

The class-level fix is a bounded multi-screen advance loop that taps
`nav_btn_next` until the form auto-finalizes, then exits on the anchor of
**wherever that finalize actually lands**. There are two of them, and they
differ ONLY in that exit anchor:

- `content-form-finish.yaml` — exits + asserts on the StandardHomeActivity
  home grid (`${SELECTOR:learn-home-start-tile}`, the Start / View Job
  Status / Sync / Log out surface, "1 form sent to server!").
- `content-form-finish-to-suite.yaml` — exits + waits on
  `${SELECTOR:learn-suite-menu}`, a display-mode-agnostic regex alternation
  over the MenuActivity containers (dimagi-internal/ace#1127) that matches
  the suite root AND a module's own one-level-in form list.

**Which one is correct is decided by the same `get_form().post_submit` field
that decides the re-entry recipe** — the two are one 2x2, not two independent
choices (dimagi-internal/ace#1566, the finalize half of the #1071 class):

| Learn app shape | `post_submit` | finalize recipe | re-entry recipe |
|---|---|---|---|
| multi-module | `module` | `content-form-finish.yaml` | `learn-suite-reentry.yaml` |
| multi-module | `previous` (**Nova's default**) | `content-form-finish-to-suite.yaml` | `learn-suite-reentry-from-module.yaml` |
| single-module | any | `content-form-finish-to-suite.yaml` | none (see § SINGLE-MODULE Learn app) |

**The finalize column reads per APP; the re-entry column reads per FORM
(dimagi-internal/ace#1633).** `content-form-finish-to-suite.yaml` exits on
`${SELECTOR:learn-suite-menu}`, a regex alternation that matches the module
form list AND the suite root, so it is correct wherever a `previous` finalize
lands. The re-entry is not: `learn-suite-reentry-from-module.yaml` is an
unconditional `back`, which is right only when the finalize actually landed
one level in. Pick it per form, from the OWNING MODULE's shape, and call it
guarded — see § Suite re-entry between modules.

**Read `post_submit` off the blueprint before you pick.** On a multi-module
app whose forms are `post_submit: previous`, the finalize lands on the
module's own form list, one level inside the suite — the home grid never
renders. `content-form-finish.yaml` cannot terminate there: its advance loop
is guarded on `notVisible: ${SELECTOR:learn-home-start-tile}` (true forever
on a menu screen) while the inner `visible: ${SELECTOR:form-nav-next}` guard
no-ops on a menu, so all 12 bounded slots burn doing nothing and the terminal
`assertVisible ${SELECTOR:learn-home-start-tile}` dies with
`Assertion is false: "Start" is visible` — the same signature #1071 observed
live for the re-entry half on spark-facilitator/20260728-1338, one step
earlier in the loop. Live repro of the finalize half:
bednet-check-2-visit/20260820-0832 (2 CommCare modules, 5 forms, all
`post_submit: previous`; workaround recorded in that run's
`journey-learn.yaml` header). `content-form-finish-to-suite.yaml` is correct
there because `learn-suite-menu` matches that module form list, and
`learn-suite-reentry-from-module.yaml` (`back` → suite root) then restores
`learn-tap-module`'s pre-state.

Call the chosen recipe once per content form (pass `SCREENSHOT_NAME`):

**Name a Learn module's frames `journey-learn-m<N>-<slug>`** — `m`, the module's
number, then a hyphen (`m0`/`m1`/`m01`; 0- or 1-based, padding allowed). The
training-deck binder finds each lesson's frames by this prefix
(`LEARN_MODULE_STEP` in `lib/training-deck-frames.ts`). It also accepts
`l<N>` (connect-fi/20261018-1440) and `module<N>` / `lesson<N>`, but any other
shape is invisible to it: the lesson slides then merge away into one "other
sections" slide (ace#3240). *Enforced:* `test/lib/training-deck-frames.test.ts`.


```yaml
# ── multi-module, post_submit: module ────────────────────────────────
- runFlow:
    file: learn-tap-module.yaml
    env:
      MODULE_NAME: "1. Program Orientation"
      FORM_NAME: "Program Orientation"
- runFlow:
    file: content-form-finish.yaml
    env:
      SCREENSHOT_NAME: "journey-learn-m0-orientation-finished"
# device is now back on StandardHomeActivity home — re-enter the suite
# before the next module (see § Suite re-entry between modules).
- runFlow:
    file: learn-suite-reentry.yaml
    env:
      REENTRY_LABEL: "-m1"        # distinct per module boundary (ace#2182)
```

```yaml
# ── multi-module, post_submit: previous (Nova's default) ─────────────
- runFlow:
    file: learn-tap-module.yaml
    env:
      MODULE_NAME: "1. Program Orientation"
      FORM_NAME: "Program Orientation"
- runFlow:
    file: content-form-finish-to-suite.yaml
    env:
      SCREENSHOT_NAME: "journey-learn-m0-orientation-finished"
# device is now on the MODULE's own form list (or, if THIS module held one
# auto-skipped form, already at the suite root) — so the `back` is GUARDED
# on the next module's row (see § Suite re-entry between modules, ace#1633).
- runFlow:
    when:
      notVisible:
        text: "2. Spot-check training"
        below:
          id: "${SELECTOR:learn-suite-menu}"
    commands:
      - runFlow:
          file: learn-suite-reentry-from-module.yaml
          env:
            REENTRY_LABEL: "-m1"  # distinct per module boundary (ace#2182)
```

Do NOT hand-chain `form-advance.yaml` + `form-submit.yaml` for content
forms — both `content-form-finish*` recipes subsume the single-screen and the
multi-screen cases **up to their slot count** (the bounded loop no-ops its
remaining advances once the form auto-finalizes on its only/last screen; past
the bound, see the next paragraph). Reserve explicit
`form-advance` → answer-tap → `form-submit` sequencing for QUIZ /
assessment forms with required inputs (per the MANDATORY answer-tap rule
below) — neither `content-form-finish*` recipe selects answers, so pointing
one at a required-input quiz stalls on `warning_root` ("Sorry, this response
is required!"; jjackson/ace#646).

**The loop is bounded — count the form's screens and pre-advance the excess
(dimagi-internal/ace#2574).** Each `content-form-finish*` recipe is an
UNROLLED sequence of guarded `nav_btn_next` taps, not a `repeat:`
(`repeat` is not in the recipe-validator allowlist), so it can cross only a
fixed number of screens:

| finalize recipe | `nav_btn_next` slots |
|---|---|
| `content-form-finish.yaml` | 12 |
| `content-form-finish-to-suite.yaml` | 14 |

Nova builds a lesson as one top-level `label` per screen, so lessons now
routinely exceed that (spark-facilitator/20261001-2208: 10, 14, **20**, 11,
**15**, 12 screens). A form with more screens than the slots runs out of taps,
the terminal anchor assert fails, the form never finalizes, its `learn_module`
never registers, and Learn stays below 100% with Deliver locked (#897).

So, per content form: read `get_form`, count its screens `S` (every top-level
field that is neither `hidden` nor `relevant`-gated; a `group` is ONE screen —
never over-count, because a bare advance past the last screen finalizes the
form early and the next one fails on a menu), and if `S` exceeds the
chosen recipe's slot count `N`, emit **`S - N` bare `form-advance.yaml`
steps** (no answer tap; each with its own `SCREENSHOT_NAME`) between
`learn-tap-module` and the `content-form-finish*` call, so at most `N` screens
are left for the loop. A form with exactly `N` screens fits. Example —
Lesson 3 (20 label screens) on a `-to-suite` app needs 6 bare advances first.
Do NOT hand-write a longer finalize loop in the journey recipe; the static
palette's loop is the calibrated one.

*Enforced:* `recipe-sanity-probe` fails `content-form-finish-overrun` when a
form walked by `content-form-finish*` has more screens left (after the bare
advances in front of the call) than that recipe's slots. It counts a LOWER
bound — `hidden` and `relevant`-gated fields are not counted — and is
field-gated (inert unless Step 2.6 supplies `fields`). The slot table above is
pinned in `CONTENT_FORM_FINISH_SLOTS` and locked to the palette files by
`test/mcp/mobile/recipe-sanity-probe.test.ts`.

##### Screenshot names are caller-bound — never rely on a palette default (dimagi-internal/ace#1033)

Four palette pieces name their screenshot from a caller-supplied env var:
`form-advance.yaml` (`SCREENSHOT_NAME`), `content-form-finish.yaml`
(`SCREENSHOT_NAME`), `content-form-finish-to-suite.yaml` (`SCREENSHOT_NAME`),
and `form-submit.yaml` (`SCREENSHOT_NAME_PRE_SUBMIT` +
`SCREENSHOT_NAME_POST_SUBMIT`). **Every single `runFlow` into one of them MUST
bind every one of those keys in its own `env:` block, with a name unique to
that call site.** An unbound call now FAILS `mobile_validate_recipe` with the
`runFlow-unbound-screenshot-name` lint rule.

**Why there are no palette-side defaults.** A Maestro flow's own top-level
`env:` block does not default *under* caller-passed env — it **overrides** it.
Measured against the pinned Maestro 2.5.1 source: the subflow's `env:` becomes
a `DefineVariablesCommand` prepended inside the subflow body, the caller's env
becomes another one prepended in front of that, and `Orchestra.runSubFlow`
executes both in list order with an unconditional `putEnv` — so the subflow's
block writes last and wins. Live-confirmed on
bednet-spot-check/20260728-2222: the journey passed `journey-learn-result` /
`journey-learn-submitted` and the files that landed on disk were
`form-submit-pre.png` / `form-submit-post.png` (the palette defaults). The
ace#852 `env:` fallbacks therefore *defeated* per-journey naming rather than
backstopping it, and were removed.

Unbound, Maestro renders the unset placeholder as the literal string
`undefined`, so the frame lands as `undefined.png` — and two unbound shots in
the same subflow overwrite each other. Both symptoms were observed live.

**Name `SCREENSHOT_NAME_PRE_SUBMIT` for the LAST QUESTION, never for a result
(dimagi-internal/ace#1853).** `form-submit.yaml` shoots that frame *before* the
tap that advances, so it is always a question — and on a score-gated quiz it is
the last item, not the score. Naming it `…-result` / `…-score` / `…-passed` is
therefore always false, and false in the direction that misleads: anything
reading the manifest by name captions it as the certification screen. It has
gone wrong three times — `journey-learn-m6-assessment-result` on
spark-facilitator/20260828-0703 (an ordinary assessment item),
`journey-learn-gate-result` on hh-poverty-targeting/20260828-0702 (filed in the
manifest between `…-gate-q9-answered` and `…-gate-submitted`), and once in this
repo's own lint fixture.

It is also now a collision. The score screen **is** captured: the score-gated
FINISH branch derives it as `<PRE_SUBMIT>-result`. So binding PRE_SUBMIT to
`…-assessment-result` puts the genuine outcome at `…-assessment-result-result`
while the misleading name keeps the clean one. Use `…-last-item` (or any name
describing the question), bind nothing extra for the score screen, and let the
palette derive it. *Enforced:* the `pre-submit-screenshot-name-claims-outcome`
rule in `mcp/mobile/recipe-lint.ts`, run by `mobile_validate_recipe`.

Historical context: the single-screen
over-step on bednet-spot-check run 20260528-0556 Phase 6 (a `form-advance` +
`form-submit` over a one-screen "Introduction" form) is also subsumed —
`content-form-finish.yaml` handles one-screen and N-screen content forms
under one contract.

##### Suite re-entry between modules — pick the variant PER FORM, then guard the call

**You MUST re-enter the suite root between every module** — the next
`learn-tap-module` asserts `screen_suite_menu_list` at the SUITE ROOT as its
pre-state and hard-fails otherwise (jjackson/ace#646 Gap 2).

**Where a finalize lands is NOT fixed — read it off the blueprint
(dimagi-internal/ace#1071).** `get_form` reports `post_submit` per form, and
it decides which re-entry recipe to compose:

| `post_submit` | Where the finalize lands | Re-entry recipe |
|---|---|---|
| `module` | StandardHomeActivity — the home grid (Start / View Job Status / Sync / Log out) | `learn-suite-reentry.yaml` (tap Start → wait `screen_suite_menu_list`) |
| `previous` (**Nova's default**) | the screen the form was entered FROM: the MODULE's own form list when that module HAS one, else the suite ROOT | `learn-suite-reentry-from-module.yaml` (`back` → wait `screen_suite_menu_list`), **called guarded** — see below |

**The choice is per FORM, not per APP (dimagi-internal/ace#1633).**
`post_submit: previous` means "the screen you came from", and on a
multi-module app that is **not the same screen for every module**: CommCare
**auto-skips** a module's intermediate one-row form list when the module
holds exactly ONE form whose display name DIFFERS from the module name
(`learn-tap-module.yaml`'s header records that behaviour as live-observed).
So for each form, read the shape of the module that OWNS it:

- **The module renders a form list** — it holds TWO OR MORE forms, or exactly
  one form whose name EQUALS the module name (no auto-skip). `previous` lands
  on that form list, one level inside the suite →
  `learn-suite-reentry-from-module.yaml` (`back` → suite root).
- **The module was auto-skipped** — exactly ONE form, whose name DIFFERS from
  the module name. There was no form list on the way in, so there is none to
  come back to and `previous` is the suite ROOT → the walk is already at the
  re-entry postcondition, and the re-entry must be a **no-op**. An
  unconditional `back` fired from the suite root exits the suite entirely and
  the following 15s wait then expires — the same signature #1071 records for
  the wrong variant.

**One app can be BOTH shapes at once,** which is exactly what a per-app
reading cannot express. Live: `bednet-check-2-visit/20260825-1310`, Nova Learn
app `80145765-6ad8-4617-8b5b-9ec2a4fa4bc1` — module "Baseline check" holds ONE
form ("What you know now", a different name → auto-skipped), module
"Spot-check training" holds TWO ("Training", "Final check" → a real form
list), and every form is `post_submit: previous`. Following the table per app
and firing an unconditional `back` after module 1 walks back OUT of the suite
before module 2 is ever entered — Learn never reaches 100% and Deliver stays
locked (the #897 consequence).

**Compose the call GUARDED POSITIVELY on the row you need next** — the next
module's suite-root row — so it is a no-op when the finalize already landed at
the root:

```yaml
# after the last form of module N, before module N+1's learn-tap-module
- runFlow:
    when:
      notVisible:
        text: "<NEXT MODULE ROW LABEL>"        # verbatim from get_app
        below:
          id: "${SELECTOR:learn-suite-menu}"
    commands:
      - runFlow:
          file: learn-suite-reentry-from-module.yaml
          env:
            REENTRY_LABEL: "-m<N>"  # distinct per call site — e.g. the module index (ace#2182)
```

Guard on the row you WANT (`notVisible` the next module row ⇒ we are not at
the root yet ⇒ go back), never on the absence of the other branch's surface —
the same lesson `connect-resume-opp.yaml` and `deliver-form-walk.yaml` Level 1
already encode. This composition is also what makes the rule safe under the
one fact here that is an INFERENCE rather than a live observation: the
blueprint shapes above are quoted verbatim from `get_app`, but "an
auto-skipped module's `previous` lands on the suite root" is derived from
`learn-tap-module.yaml`'s recorded auto-skip plus the plain meaning of
`previous`, and has not been re-observed on a device. The guard is correct
under either landing; a second unconditional variant would not be.

Composing the wrong VARIANT hangs the walk. `learn-suite-reentry.yaml` opens
with a 30s `extendedWaitUntil` on the home "Start" tile; from a module form
list that tile never renders, so a multi-module walk dies after form 1 with
`Assertion is false: "Start" is visible`. Live repro:
spark-facilitator/20260728-1338 (9 modules, all `post_submit: previous`) —
the pre-test finalized and synced cleanly, then the walk hung, with the dump
showing action bar "Baseline check" and a single row "Pre-test (baseline)".

The per-module loop is therefore:

```
learn-tap-module → content-form-finish (or quiz answer-taps + form-submit)
                 → <re-entry variant per the table, GUARDED per above>
                 → (next module's learn-tap-module)
```

The FIRST suite entry (post-claim) still uses `learn-launch.yaml` regardless
of `post_submit` — it enters from the Connect handoff, not from a finalize.

**Do not try to collapse the two variants into one guarded recipe.** The
module form list and the suite root share the same `screen_suite_menu_list`
id, so no on-screen signal distinguishes "one level in" from "already at the
root"; a guard keyed on that id would press `back` out of the suite entirely
on a `post_submit: module` app. The app-metadata branch above is the reliable
discriminator. (See the header of `learn-suite-reentry-from-module.yaml`.)
That is NOT in tension with the call-site guard above: the guard there is
keyed on the NEXT ROW'S NAME — a per-journey value the palette cannot know —
not on the shared container id. Parameterising the recipe on a
`${NEXT_ROW_NAME}` would move the guard back into the palette; until it does,
the guard lives at the call site.

##### SINGLE-MODULE Learn app — use `content-form-finish-to-suite.yaml`, NOT the home round-trip (jjackson/ace#894)

The home-grid contract above holds when each Learn module is its OWN CommCare
module. But Nova frequently builds a Learn app as **one CommCare module holding
ALL N forms** (proven live on hh-poverty-targeting/20260722-1341: one module
"Poverty Targeting Enumerator Training" with 7 forms). In that shape, finishing
a form returns to the **N-form suite list (`screen_suite_menu_list`)**, NOT to
the StandardHomeActivity home grid — so `content-form-finish.yaml`'s terminal
`assertVisible learn-home-start-tile` fails, and `learn-suite-reentry.yaml`
(home→suite) mis-navigates. This was the ace#894 Deliver-blocked-Phase-6 class.

Detect single-module by reading the Nova blueprint (`get_app`): if the Learn
app has exactly ONE module containing every form, author `journey-learn.yaml`
as **drill suite-root → the module → its form list ONCE**, then per form:

```
learn-tap-module (taps the FORM ROW directly from the suite list)
  → answer any quiz inputs
  → content-form-finish-to-suite   (finalizes back to screen_suite_menu_list)
  → (next form's learn-tap-module — NO learn-suite-reentry)
```

`content-form-finish-to-suite.yaml` is `content-form-finish.yaml` re-keyed on
`${SELECTOR:learn-suite-menu}` (the suite list) instead of the home tile: a
bounded guarded advance loop (`tapOn form-nav-next` while the suite list is not
visible), a `form-nav-finish` fallback for the score-gated two-screen FINISH
(#569), then `assertVisible learn-suite-menu`. **Omit `learn-suite-reentry`
entirely** — there is no home round-trip in a single-module app. Multi-module
apps keep the finalize + re-entry loop above, whose BOTH halves are picked
from `post_submit` (dimagi-internal/ace#1566) — a multi-module
`post_submit: previous` app also finalizes with
`content-form-finish-to-suite.yaml`, but unlike the single-module shape it
still needs `learn-suite-reentry-from-module.yaml` between modules.

**Verify each transition you author against the selector map for the
active APK (`mcp/mobile/selectors/connect-<apkVersion>.yaml`, default
`2.63.2`), and against the palette recipes in
`mcp/mobile/recipes/static/`** — those two are live-calibrated and carry
per-row provenance. `docs/mobile-atlas/connect-2.63.2.md` is the narrative
companion — which screen replaces which, what fires in between, what a
transition changes as a side-effect. It is written against the default APK,
but it is **partial**: read a section's provenance tag before relying on it
(`calibrated-2.63.2` vs `carried-from-2.62.0-unverified` vs `uncovered`),
and note that its carried-over § 5 surfaces point back into the older
2.62.0 atlas, whose "Open questions" are stale — several have since been
answered in recipe headers rather than in either atlas. If a recipe needs
a transition neither source documents, flag it in the recipe header
comment and file it, rather than treating an atlas's silence as evidence.

Each `is_smoke=true` journey's recipe **must** include the Connect-
login + opp-claim prefix so it can run from a cold boot (the cloud
backend's standard state). Non-smoke journeys can assume warm state
and skip the prefix — but flag that assumption in the YAML header
comment so a reviewer doesn't try to run them cold.

Caught in vivo on leep Phase 5 attempt 10 (2026-05-13). Before this
guidance landed, the smoke recipes (`journey-learn.yaml` /
`journey-deliver.yaml`) emitted the broken `launchApp +
tapOn:<app-name>` model, the live `tapOn` never found a target, and
the recipes failed with selector-miss errors — even though the
emulator + Maestro + cloud-stack were healthy.

#### Maestro feature-compat — local vs lease parity

As of 2026-05-19, **both backends run Maestro on the v2.x line**
(local: v2.5.1 via the official installer; the leased image: v2.5.1 pinned
in `infra/capabilities/android-emulator/image/scripts/30-maestro.sh`). The lag table below
documents the historical drift class — it's NOT currently active.
Re-baseline if the versions ever diverge again (track local via
`maestro --version`, cloud via `ACE_MOBILE_AMI_VERSION`):

| Property | Local AVD | Cloud |
|---|---|---|
| `visibilityPercentage` | works | **historically rejected with `Unknown Property` on the v1.36-era AMI** |
| `point: "x,y"` | works | works |
| `id:` matcher | works | works |
| `text:` matcher | works | works |
| `index:` for multi-match | works | works |
| `optional: true` (under mapping form) | works | works |

Origin: leep Phase 5 attempt 10 — `connect-claim-opp.yaml` shipped
with `visibilityPercentage: 30`, the v1.36-era cloud Maestro rejected
the whole recipe with `Unknown Property` before the first step
executed. Property removed in 0.13.194; AMI bumped past the drift in
the 2026-05-12-2142 bake. Keep the prevention discipline regardless:
when in doubt, omit version-specific properties — the default
substring + visibility threshold is usually enough.

#### Selector placeholder gate — STRICT

Every `tapOn:text:` matcher in a generated recipe MUST be either:
- A **Nova-confirmed live form-field label** (read via `get_form`
  or `get_module` per the "Use live labels" section below), OR
- A `${SELECTOR:logical-name}` placeholder that resolves against
  `mcp/mobile/selectors/connect-<apk-version>.yaml` via
  `mobile_resolve_selectors` (Step 3.4)

The reason the placeholder path is mandatory for non-form-label
matchers: Connect-integrated CommCare has surface elements
(nav-drawer items, opp-card buttons, Start buttons, etc.) whose
labels are NOT in `get_form`. If a recipe hard-codes their text,
the matcher drifts silently when Connect's UI updates. The
selector map at `connect-<apk>.yaml` is the **single point of
calibration** — populate it via `connect-baseline-screenshots`,
then every recipe that references the same logical name updates
in lockstep.

The fallback rule: if you're tempted to write
`tapOn: { text: "Some Surface Label" }` and that label is NOT
from Nova's `get_form`, STOP. Add a logical name to the selector
map (or a placeholder for one) and use `${SELECTOR:<name>}`
instead. The agent at Step 3.4 will halt with `[BLOCKER]` if any
unresolved placeholder ships — that's the forcing function.

**Use live labels from Nova's `get_form` response, not the PDD
brief's labels** (per [#115 finding 2](https://github.com/jjackson/ace/issues/115)).
The PDD brief uses pre-build naming conventions (`L0 — Why this
matters`, `F1 — Shop Registration`, `Stage 1 — Market Analysis`)
that Nova's autobuild and CommCare's app-editor rewrite into different
strings on the live device (`1. Why this matters`, `Stage 1: shop
visits & interviews`, etc.). `tapOn:text` matchers calibrated against
the brief never hit live screens.

For every `tapOn:text` matcher in a recipe:
- Read the label from `get_form({app_id, moduleUuid, formUuid})`'s
  response — Nova returns each form's `label` and each field's `label`
  exactly as CommCare will render them after autobuild's scaffold pass.
  Nova is **uuid-addressed** (2026-07-31; see
  `playbook/integrations/nova-integration.md § The 2026-07-31
  uuid-addressing migration`) — no tool accepts `moduleIndex` /
  `formIndex` / a bare `form_id`. Resolve the whole map with ONE
  `get_app({app_id})` (its blueprint prints `[uuid …]` on every module,
  form, and field) and reuse it for every read below; for a single
  semantic name, `search_blueprint({query, app_id})`.
- Use that string verbatim in the recipe's `tapOn:text` matcher.
- For module-list / form-list screens, read the parent module's `label`
  from `get_module` and apply the same rule.

`mobile_validate_recipe` is a static lint that accepts any
syntactically-valid string — it cannot detect a brief-vs-live drift.
Step 4 (below) adds a runtime smoke check that catches it.

#### Score-gated assessments DO render a result screen — both branches (ace#1302, confirms #569)

`spark-facilitator/20260813-2126` reported that a score-gated Learn assessment
**auto-finalized on the last answer** and went straight to `1 form sent to
server!`, so the CBF completed a payment gate with no on-screen confirmation.
The report was explicit that it had observed the **pass path only** and could
not say whether the platform or the app was at fault.

**Settled on-device, both branches** — CommCare 2.63.2 / `ACE_Probe_API_34`,
2026-08-14, on a single-question score-gated quiz with trailing
relevance-gated `result_pass` / `result_retry` labels:

| answer | `user_score` | what rendered |
|---|---|---|
| correct | 100 | `PASSED. You scored 100 percent.` + `FINISH` |
| wrong | 0 | `NOT PASSED. Go back to module 1 and read it again.` + `FINISH` |

```
cc:nav_btn_finish       [126,293][1059,419]
cc:nav_btn_finish_text  'FINISH'
TextView                'NOT PASSED. Go back to module 1 and read it again.'
```

Two consequences for how you diagnose this:

1. **A missing result screen is an APP-SHAPE defect, not platform behaviour.**
   The platform renders trailing relevance-gated labels on both branches, so
   if a walk never sees one, look at the app: are the labels reachable in form
   order, is `user_score` computed before they are evaluated, are their
   `relevant` expressions exhaustive? Do not record it as a CommCare
   limitation.
2. **ace#569's two-screen finalize needs NO qualifier.** #1302 suggested the
   rule might only hold for multi-question quizzes. It held on a
   SINGLE-question score-gated quiz: `nav_btn_next` advanced to the result
   screen, and `nav_btn_finish` was present there. So `form-submit.yaml`'s
   score-gated branch is correct as written, and a walk that reports
   `nav_btn_finish` not visible has not reached the result screen — that is
   the thing to investigate, not the rule.

#### CommCare's CHOICE DIALOG — repeat junctures and the form-exit prompt (ace#1007, #1290)

Two surfaces ACE had zero coverage for turn out to be **the same component**,
live-verified on CommCare 2.63.2 / `ACE_Pixel_API_34` 2026-08-14. Branch on
`${SELECTOR:form-choice-dialog-title}` to tell them apart — and note the
buttons are addressed DIFFERENTLY on each, which is the trap:

| Dialog | Title | Buttons |
|---|---|---|
| form exit | `Exit Form?` | **TWO buttons sharing ONE id** `choice_dialog_panel` — `STAY IN FORM`, `EXIT WITHOUT SAVING`. Disambiguate by TEXT (it is CommCare chrome, stable across apps). |
| repeat juncture | `Add a new <repeat label>?` | **THREE INDEXED buttons** — `_1` GO BACK, `_2` ADD A NEW …, `_3` DO NOT ADD. Prefer the INDEX: `_2`'s label interpolates the repeat's own name, so a text matcher is app-specific and brittle. |

**Repeat junctures (ace#1007).** A `kind: repeat` field brackets each
repetition with an entry prompt and an "add another?" exit prompt. Until now
neither had a selector, an atlas section, or a palette recipe, so
`app-test-cases` could not author the roster leg at all and MARKED the region
instead — and the Deliver leg then hard-failed there on-device. To walk PAST a
repeat without entering it, tap `${SELECTOR:form-repeat-juncture-skip}`
(`DO NOT ADD`); verified live to land on the question following the repeat. To
enter one, tap `${SELECTOR:form-repeat-juncture-button}`.

**The form-exit prompt (ace#1290).** A back-press from inside a form lands
here, NOT on the previous screen. That is what killed the Deliver smoke on
`spark-facilitator/20260813-2126`: `form-submit` did not finalize the
registration form, the inter-leg back-walk pressed back twice, and the walk
asserted `Start` while sitting on `Exit Form?`. Any guarded back-walk between
Deliver legs MUST handle this dialog — see the two-leg re-entry snippet above
(ace#1191) — and a `form-submit` that leaves the device here has NOT submitted,
whatever its POST_SUBMIT screenshot shows.

#### `kind: date` questions and the inline DatePicker — MANDATORY (ace#1081, #1300)

The skill's answer-tap rule enumerates `single_select`, `image`, `text`,
`decimal`, `geopoint` and hidden fields. It says nothing about
`kind: date`, and the selector map carried no date row until 2026-08-14.

**The widget, live-calibrated** (CommCare 2.63.2 / `ACE_Pixel_API_34`,
portrait 1080x2400):

```
DatePicker                  [214,1208][865,1765]      (no resource-id — match by class)
  NumberPicker  month       [235,1250][403,1723]      numberpicker_input "Aug"
  NumberPicker  day         [445,1250][613,1723]      numberpicker_input "14"
  NumberPicker  year        [655,1250][823,1723]      numberpicker_input "2026"
```

Rows: `form-date-picker`, `form-date-picker-container`,
`form-date-picker-column`, `form-date-picker-input`.

**NEVER scroll a field-list screen from its centre when it carries a date
question.** Each NumberPicker column is `scrollable=true`, so a
centre-origin swipe — which is exactly what `scrollUntilVisible` issues —
is **consumed by the picker and spins the date**. Measured on-device:

```
portrait   swipe x=540  (centre)   Aug 14 -> Aug 22    page did NOT move
landscape  swipe x=1200 (centre)   Aug 22 -> Aug 25    page did NOT move
landscape  swipe x=300  (edge)     Aug 25 -> Aug 25    no mutation
```

Both halves bite: questions below the picker are unreachable, **and** a
payment-gating field is silently changed by an automation gesture with no
error and nothing able to assert against it. Use `safeScrollOriginX`
(`lib/fieldlist-gestures.ts`) to pick an origin outside the picker's
x-range, and assert the date via `form-date-picker-input` afterwards —
that read-back is the only surface that reports what the picker now holds.

**Driving the picker is APK-SPECIFIC — look it up, never transcribe it
across versions.** `lib/date-picker-drive.ts` `datePickerDriveFor(apk)`
returns the calibrated mechanism for the selector map's APK; an APK it does
not list has **no** calibrated drive (calibrate live first).

| APK | drive | evidence |
|-----|-------|----------|
| 2.63.2 | `tap-next-cell` — tap the Button below `numberpicker_input` | ace#1081: Aug 14 → 15 → 16, read back |
| **2.64.0** | **`row-fling`** — one-row upward swipe on the DAY column | ace#2518: 27 → 28, read back; the tap is a no-op |

**2.64.0 — one-row fling (ace#2518).** On APK 2.64.0 the next-cell tap is a
**silent no-op**: Maestro reports `COMPLETED`, the picker stays on today,
and FINISH is then refused by the form's constraint. Measured on
spark-facilitator/20260926-1413 Phase 6, four candidates on one open form,
each read back from a ui dump — only the fling moved the day:

```
relational tap below/rightOf/leftOf numberpicker_input     27 -> 27
tapOn {text: "28", below: {text: "27"}}  (the next cell)   27 -> 27
tap input + eraseText + inputText "28" + hideKeyboard      27 -> 27  (hideKeyboard = BACK -> "Exit Form?")
swipe start 529,968 end 529,818 duration 600               27 -> 28  constraint cleared
```

Emit the fling from the helper, never from hand-typed pixels:

```ts
import { dayStepFlingYaml } from '../../lib/date-picker-drive';
dayStepFlingYaml();   // - swipe: { start: 529, 968, end: 529, 818, duration: 600 }
```

```yaml
# group `next_meeting_date` — `. > today()`: advance the day by one (ace#2518, 2.64.0)
- assertVisible:
    ${SELECTOR:form-date-picker}
- swipe:
    start: 529, 968
    end: 529, 818
    duration: 600
```

The gesture runs from the centre of the day column's NEXT cell to the centre
of its CURRENT cell — exactly one row. Maestro 2.5.1 cannot anchor a
*bounded* swipe on an element (`swipe: {from: <selector>, direction: UP}`
flings to 10% of screen height — many rows, the ace#1300 hazard), so the
coordinates are derived at authoring time: `dayStepFling(cells)` takes the
day column's current/next cell bounds, and its default
(`DATE_PICKER_2_64_0_OBSERVED`) is the recorded layout — a date question at
the **top of its field-list screen** on 1080x2400. If the date question sits
lower on its screen (another question above it on the same screen), pass the
bounds from a ui dump of that screen instead of the default. **Keep the
form's own constraint as the loud check**: if the fling misses, FINISH is
refused with the constraint message rather than a wrong date being filed.
Never emit the ace#1081 relational tap for 2.64.0 — `recipe-lint`'s
`date-picker-next-cell-tap-noop` rule rejects it at `mobile_validate_recipe`
and at dispatch.

**Flinging AFTER a constraint refusal: settle first, then guard a retry
(ace#2693).** When the recipe deliberately trips the date constraint first
(tap next/FINISH → `assertVisible` the refusal) and only then flings, the
fling issued straight after the refusal was a **silent no-op** — Maestro
`COMPLETED`, day still `05`, banner still up, FINISH refused again. The same
swipe a minute later on the same open form moved `05 → 06`. Insert a settle
before the fling and one refusal-guarded retry after it:

```yaml
- assertVisible:
    text: ".*<refusal message, verbatim from the form's constraint>.*"
- waitForAnimationToEnd:
    timeout: 3000            # let the refusal's scroll/banner animation finish
# ...the dayStepFlingYaml() swipe...
- waitForAnimationToEnd:
    timeout: 2000
- runFlow:                   # one retry, only if the refusal is still up
    when:
      visible:
        text: ".*<same refusal message>.*"
    commands:
      # ...the same dayStepFlingYaml() swipe...
      - waitForAnimationToEnd:
          timeout: 2000
```

Evidence (spark-facilitator/20261004-1706, `reschedule_date` `. > today()`,
2.64.0, 1080x2400): no-op dispatch `1791201121968-7qzewb`; passing dispatch
`1791202061636-24lmor` with this exact shape — the first fling moved `05 →
06` and the guarded retry was SKIPPED. The mechanism (the refusal's
animation absorbing the gesture) is a hypothesis from one observation each
way, which is why the retry stays: it costs nothing when the first fling
lands. `dayStepFlingYaml()`'s emitted swipe is unchanged — this is
composition around it, not a different gesture. On a recipe that does NOT
trip the refusal first, no settle is needed.

**Going back one day (ace#2785).** The mirror gesture: a one-row DOWNWARD
fling on the day column, from the CURRENT cell's centre to the NEXT cell's
centre. Emit it from the helper, with the day cells read from a ui dump of
the form's screen:

```ts
import { dayStepBackFlingYaml } from '../../lib/date-picker-drive';
dayStepBackFlingYaml(cells);   // default cells: - swipe: { start: 529, 969, end: 529, 1119, duration: 600 }
```

```yaml
# `session_date` — Day 1 = yesterday: step the day back by one, then READ IT BACK
- swipe:
    start: 529, 969
    end: 529, 1119
    duration: 600
- waitForAnimationToEnd:
    timeout: 3000
- assertVisible:
    id: "${SELECTOR:form-date-picker-input}"
    text: "15"                 # the expected day — yesterday's day-of-month
```

Measured on spark-facilitator/20261004-1706 "Other Meeting Record"
(2026-10-17, 1080x2400, date question at the top of the first screen;
day cells previous `[445,733][613,906]`, current `[445,906][613,1032]`,
next `[445,1032][613,1206]`): `16 → 15`, and the same swipe again
`15 → 14`. The read-back assert is REQUIRED. Unlike the forward drive, a
backward step has no loud check of its own: a `. >= today() - 14` rule
accepts a wrong step, because a wrong step still lands inside the window.

Residuals (not yet observed on-device): month/year rollover in either
direction (day 1 → last day of the previous month), and a picker below the
fold. The forward derivation now holds at two screen positions (the same
2026-10-17 screen moved `14 → 15` with the derived forward fling), and two
back flings in a row each moved exactly one day. A constraint with a
far-future floor still needs live calibration before authoring.

**2.63.2 — one tap per step (ace#1081).** Each column renders three
children in order:

```
Button    previous value      day column [445,1250][613,1423]   "13"
EditText  numberpicker_input  day column [445,1423][613,1549]   "14"   <- current
Button    next value          day column [445,1549][613,1723]   "15"
```

**On 2.63.2, tapping the lower Button increments that column by exactly
one** — measured with read-back: Aug 14 → 15 → 16 on two separate taps.
Always read the result back from `${SELECTOR:form-date-picker-input}`; never
assume the tap landed. On 2.63.2, do **not** swipe inside a column to set a
value: a *centre-of-screen* swipe moves it by an unpredictable number of
steps (Aug 14 → 22) — the ace#1300 hazard. (The 2.64.0 fling above is a
bounded one-row gesture, not that.)

So a strictly-future constraint IS walkable on both calibrated APKs, with a
single step:

```
next_meeting_date   validate: . > today() and . <= date(today() + 30)
```

The widget defaults to today, which fails `. > today()`. **One** step on the
day column (2.63.2: tap; 2.64.0: fling) makes it tomorrow, satisfying both
clauses.

#### Quiz / required-input answer-tap rule — MANDATORY

A `form-advance.yaml` (or any direct `nav_btn_next` tap) on a
required-input question with no answer selected surfaces
`warning_root` ("Sorry, this response is required!" per atlas §7),
stalling the recipe. Every required-input question in a Maestro
recipe **MUST** be preceded by an explicit answer-selection step:

```yaml
# CORRECT — answer is tapped before advancing, and the advance names its frame
- tapOn:
    text: "Public hospital"      # literal option text from Nova get_form
- runFlow:
    file: form-advance.yaml
    env:
      SCREENSHOT_NAME: "journey-learn-m1q2-facility-answered"

# WRONG — no answer tap; nav_btn_next stalls on warning_root
- runFlow:
    file: form-advance.yaml      # required-input question is unanswered
    env:
      SCREENSHOT_NAME: "journey-learn-m1q2-facility-answered"
```

**Leading (and interior) display/label screens — MANDATORY (jjackson/ace#710).**
A form does NOT always open on its first *question*. A `kind: label` /
display node (an intro, instructions, or result screen with no input widget —
only `nav_btn_next`) renders as its OWN screen. If the recipe taps an answer
option while a leading display node is on screen, the option selector isn't
present and the tap fails `selector-not-found` (caught in vivo:
bednet-spot-check/20260605-0658 Phase 6 Learn leg — the "Connect Comprehension
Check" form opened on a one-question intro label, and the answer tap landed on
the intro screen). The rule: **walk the form's field list IN ORDER and emit one
`form-advance.yaml` step for every display/label node — both leading ones
before the first input AND interior ones between inputs — with NO answer tap on
those advances** (a display node has nothing to select; it's the input-node
rule above, inverted). A form `[intro(label), q1(single_select, required)]`
therefore composes as: `form-advance` (past intro) → `tapOn: <q1 option>` →
`form-advance`/`form-submit`.

**This rule is now statically enforced** (dimagi-internal/ace#1045). It was
prose-only from #710 (2026-06) to #1045 (2026-07-31), and it recurred in that
window — a golden `journey-learn.yaml` authored a month after #710 closed did
`learn-tap-module` → `takeScreenshot` → `tapOn: <q1 option>` with no
intervening advance, so the tap landed on the `intro` label screen and killed
the Learn leg (bednet-spot-check/20260729-0002). `recipe-sanity-probe` now
counts the form's LEADING `kind: label` nodes (skipping `hidden`, which render
nothing) and fails `answer-tap-before-leading-label-advance` when the recipe
emits fewer bare advances than that between the menu-walk entry step
(`learn-tap-module` / `deliver-form-walk`) and its first answer tap — naming
expected vs found. Field-gated: it needs Step 2.6's caller to supply
`fields`, exactly like `group-field-list-per-question-walk`. It is the
inverse of the #858 permissive carve-out, which bounds the same advance
count from above; the two cannot conflict.

**The score-gated finalize (#569) is now statically enforced too**
(dimagi-internal/ace#1118): a trailing `relevant`-gated label pair means
`form-submit.yaml` performs the answer→result advance itself, so do NOT
chain an extra `form-advance` between the last required answer and
`form-submit` — the probe fails `score-gated-quiz-over-advance` when one is
present beyond what the form's UNGATED trailing label screens license.
Field-gated like its siblings, and it needs each trailing label's
`relevant` flag in the supplied `fields` (Step 2.6's caller passes it).

For each form-walk segment of a recipe:

1. Call `get_form({app_id, moduleUuid, formUuid})` — uuids off the
   `get_app({app_id})` map per § Use live labels — and inspect each
   field's `kind` + required-ness, **in document order**.
1.5. Walk the fields in order. For every leading or interior **display/label
   node** (`kind: label` / a display-only node with no input widget), emit one
   `runFlow` into `form-advance.yaml` with NO preceding answer tap (but still
   with its own `env: { SCREENSHOT_NAME: ... }` — see § Screenshot names are
   caller-bound) — it advances past the intro/instructions/result screen to the
   next node (jjackson/ace#710). Do this BEFORE the first answer tap when the
   form's first node(s) are display nodes.
2. For every `kind: single_select` field that's required, emit a
   **guarded-scroll option tap** BEFORE the `form-advance.yaml` step. The
   option label comes from the field's `options[].label` in the Nova
   blueprint — verbatim, not paraphrased, not derived from the PDD brief.

   ```yaml
   - runFlow:
       when:
         notVisible:
           text: "<literal option label>.*"
       commands:
         - scrollUntilVisible:
             element:
               text: "<literal option label>.*"
             direction: DOWN
             speed: 30
             timeout: 20000
             visibilityPercentage: 60
             centerElement: true
   - tapOn:
       text: "<literal option label>.*"
   ```

   **Both halves are load-bearing, and they fail in opposite directions
   (dimagi-internal/ace#1070).** A bare `tapOn` with no scroll misses any
   option below the fold — a long option label on a small screen pushes the
   4th option off, and this was measured on trilingual labels (en/nya/tum),
   where a 4-option question routinely rendered ~3 options per screen. This
   case is **back in full force as of 2026-08-17** (PR #1463, superseding ace#968/#1391): ACE
   builds a real per-language layer again, and a translated label is often
   LONGER than its English source, so plan for the same off-screen options
   the trilingual builds hit. (It briefly went rare during the English-only
   window, 2026-08-14..2026-08-17.) Both halves below are unchanged. But an
   *unconditional* `scrollUntilVisible` is equally wrong: on a question
   whose options already fit, there is nothing to scroll, and CommCare's
   form view reads the resulting no-op swipes as **backward form
   navigation**, walking the flow out of the form to an "Exit Form?"
   dialog. The `when: notVisible` guard is what makes one recipe correct
   for both shapes.

   Live repro of each half, same app, same walk
   (spark-facilitator/20260728-1338, 2026-07-30): pre-test q4's correct
   option sat below the fold and a bare tap could not reach it; post-test
   q6's four options all fit, and an unconditional scroll exited the form.

   Do NOT reach for `scroll` or a fixed swipe count instead — those are
   unguarded by construction and reproduce the q6 failure.

   **This snippet is for a question that owns its screen, and the guard is
   global because the TAP is global.** Inside a `kind: group` field-list
   the tap is `below:`-scoped — several identically-labelled questions
   share one screen — and copying this global guard in front of a scoped
   tap makes the guard a runtime no-op (ace#2426). There the guard and its
   scroll must carry the tap's own `below:` anchor: see § group-field-list
   walk item 2 → **A guard must carry the same scope as the tap it
   protects**. *Enforced:* `option-tap-guard-is-unscoped`.
3. For `kind: image` required fields, emit the photo-capture sequence
   (`camera-take-photo` → `camera-shutter-button` → `camera-save-photo`)
   before advance.
4. For `kind: text` / `kind: decimal` required fields, emit `inputText`
   with a plausible sample value before advance. **On a field-list
   (`kind: group`) screen a bare `inputText` only lands for the FIRST
   input** — CommCare autofocuses that one and nothing else. Every later
   input needs the calibrated focus sequence of § Step 3 item 3:
   unconditional centring scroll at `speed: 30` on the element
   immediately above the `EditText` (its `hint` when it has one, else the
   question label), then `tapOn: below: <that anchor>`, then `eraseText`,
   then `inputText`, then `hideKeyboard` (ace#1299, ace#1844).
4.5. For `kind: geopoint` required fields, do **NOT** `inputText` a
   `"lat lon alt accuracy"` string. A native CommCare geopoint is a
   **Capture-button widget** that reads the device GPS — not a free-text
   field — and the hidden `selected-at(<gps>, 0|1|3)` lat/lon/accuracy
   calcs only resolve from a real captured fix. (Typing a string fails:
   the value can't be entered as multiple space-separated tokens, so
   `selected-at(<gps>, 1)` throws `Calculation Error … list with only 1
   element` at runtime — jjackson/ace#686. A build that renders the
   geopoint as a plain text box is a **stale / downgraded build**: bind
   `type="xsd:string"` instead of `type="geopoint"` — `app-release-qa`
   now hard-gates that class, so a correct build always renders the real
   Capture widget.) The correct recipe sequence is: (a) ensure the
   emulator has a mock location — the cold-boot baseline already seeds a
   default fix, and `mobile_set_location` overrides it with opp-specific
   coordinates (**longitude first**; local AVD and lease backends); see
   `playbook/integrations/mobile-integration.md`, (b) tap
   `${SELECTOR:geopoint-record-location}` — the widget's button ships
   **TWO labels**, and the mapped selector is the alternation
   `(RECORD|REPLACE) LOCATION` that accepts both. It renders
   **"RECORD LOCATION"** when the field is EMPTY (live-calibrated
   2026-07-13 on hh-poverty-targeting/20260702-1456,
   dimagi-internal/ace#861) and **"REPLACE LOCATION"** when it ALREADY
   HOLDS A VALUE (live-captured 2026-09-01 on
   spark-facilitator/20260828-0703, dimagi-internal/ace#1879). The
   second label is not an edge case: a case-bound geopoint on a followup
   form is implicitly preloaded from the previous visit
   (dimagi-internal/ace#1809), so **every walk after the first against
   the same case meets REPLACE, not RECORD**. Never re-hardcode the
   single-label string — always go through the selector map, or the
   recipe passes on walk 1 and dies on walk 2. (The Button carries no
   resource-id, and the earlier "Capture Location" guess does not exist
   on-device.) (c) The tap **auto-captures** when a
   mock fix is pre-seeded — wait for the Latitude/Longitude/Altitude/
   Accuracy readout to render under the button (no separate capture
   dialog). Emit exactly:

   ```yaml
   - tapOn:
       ${SELECTOR:geopoint-record-location}
   - extendedWaitUntil:
       visible:
         ${SELECTOR:geopoint-captured-readout}   # "[\\s\\S]*Accuracy: [\\s\\S]*"
       timeout: 30000
   ```

   **Never wait on `REPLACE LOCATION` as proof of capture (ace#2878).**
   On APK 2.64.0 the button does NOT relabel after a fresh fix — it stays
   `RECORD LOCATION` with the readout rendered below it
   (smallholder-seasonal/20261012-1549: all three geopoint steps of the
   Deliver leg failed on that wait, and all three passed on-device with the
   readout wait above). *Enforced:* `mcp/mobile/recipe-lint.ts`
   `geopoint-wait-on-replace-relabel`, which `mobile_validate_recipe` and
   `mobile_run_recipe` both run. On the REPLACE branch that readout, and the
   "Location accuracy is good." label, are ALREADY on screen before the
   tap — carried over from the previous visit — so do not treat their
   presence as proof this walk captured a fresh fix. If a FUTURE APK
   version changes the widget, re-calibrate
   against a live dump of that build (per "close the loop to the source
   of truth") — never transcribe from a sibling build (that's exactly how
   the #593/#686 "GPS is a plain text field" misdiagnosis propagated).
4.7. For `kind: date` fields, the CommCare date widget **defaults to
   today**, so a date question whose `validate` accepts today needs NO
   interaction at all — emit the plain `form-advance.yaml` and the
   pre-filled default carries the screen (`. <= today()` and
   `. >= today()` constraints both fall in this class). A
   **strictly-future or strictly-past** constraint (e.g.
   `. > today() and . <= date(today() + 30)`) is different: today
   violates it, so the recipe must DRIVE the widget one day forward
   before advancing, using the APK's calibrated mechanism from
   § `kind: date` questions (2.63.2: next-cell tap, ace#1081; 2.64.0:
   one-row fling, ace#2518 — the tap is a no-op there). On an APK with
   no calibrated drive (`datePickerDriveFor(apk)` is undefined), do NOT
   guess one (banned by "close the loop to the source of truth") and do
   NOT chain `form-advance` into the constraint error: the Step 5
   date-default static gate (below) fails loud naming the field; route
   the smoke through a branch that avoids the field when the form has
   one, and otherwise halt with a `[BLOCKER]` naming the missing
   calibration. Statically verify with
   `lib/date-default-validate.ts` rather than eyeballing the
   expression. `recipe-sanity-probe`'s `form-advance-without-answer-tap`
   honours this rule: a default-accepted date — and a `kind: group`
   whose visible children are all labels — counts as a no-interaction
   screen alongside top-level labels, so the plain advance over it is
   not read as a skipped input (ace#2483). Step 2.6's caller passes each
   date field's `validate` (and `required`) in `fields` for it to judge;
   a date with no `validate` supplied is treated as default-accepted.
5. Hidden / `calculate`-only fields are auto-populated by the form
   runtime — they don't need a per-question answer step. Skip them when
   composing the answer sequence.

**Anti-pattern: generic-positional placeholders.** Do NOT emit
`${SELECTOR:radio-first-option}`, `${SELECTOR:radio-first-answer}`,
`${SELECTOR:option-1}`, or any other generic-positional logical
selector. The selector map intentionally does not provide stable
rows for "the first option" because the right answer is always a
literal label from `get_form`. Generic positional placeholders:

- hide which answer is being selected (both from a code reviewer and
  from the live-screen Maestro matcher),
- silently drift when option ordering changes between Nova rebuilds,
- pass `mobile_validate_recipe` (which is syntactic) while failing at
  Step 3.4's `mobile_resolve_selectors` gate (which is what halts the
  recipe in Phase 3 — *if* the selector is absent from the map) or at
  runtime on the live AVD (if a future map adds a brittle positional
  row).

If the recipe author would have to guess at a positional selector,
they haven't read `get_form` yet — read it first, then emit the
literal label.

**Anti-pattern: form-advance before answering.** Do NOT chain
`form-advance.yaml` (or `${SELECTOR:form-nav-next}` taps) directly
after the question rendering with no answer-selection step in between
on a required-input field. This was the canonical structural failure
on malaria-rdt run 20260522-1002 — every quiz step in the Learn smoke
recipe (`journey-learn.yaml`, id `journey-learn-pass`)
chained `form-advance` without an answer tap, stalling on
`warning_root` ("Sorry, this response is required!") before the
recipe could reach `deliver-launch.yaml`. The recipe validated as YAML
but could not advance past the first required quiz question.

Caught in vivo on malaria-rdt run 20260522-1002 Phase 6 (2026-05-22).
Both smoke recipes carried this class of defect: a quiz-retry journey
referenced an unresolved `${SELECTOR:radio-first-option}` placeholder,
and the Learn smoke (`journey-learn.yaml`, id `journey-learn-pass`)
chained `form-advance.yaml` across 10+ required-input quiz questions
with zero answer-selection steps in between.

**Write the smoke recipes to `ACE/<opp>/runs/<run-id>/3-commcare/recipes/journey-<app>.yaml`**
(NOT `app-test-cases/recipes/` — earlier drafts of this SKILL.md had
the wrong path and the recipes silently weren't being created;
[#106 finding 3](https://github.com/jjackson/ace/issues/106) fixed
this. The path must mirror the output spec at the top of the file so
Phase 6's `app-screenshot-capture` can find them.) Only the two smoke
recipes are written here; deep journeys carry `recipe: deferred` and
their files are generated later by `/ace:qa-deep`.

Create the `3-commcare/recipes/` subfolder via `drive_create_folder`
(idempotent — `findOrCreate: true` is the default) BEFORE writing the
first recipe.

### Step 3.4: Selector-resolution gate

Before writing any recipe to Drive, run a recipe-wide
`mobile_resolve_selectors` pass against the current APK selector map
(`mcp/mobile/selectors/connect-<ACE_CONNECT_APK_VERSION>.yaml`,
default `2.62.0`). At Phase 3 this applies to the two smoke recipes
(the only recipes authored here); `/ace:qa-deep` runs the SAME gate over
each deep recipe it generates on demand. For each composed recipe, call:

```
mcp__plugin_ace_ace-mobile__mobile_resolve_selectors({
  yaml: <composed recipe body>,
  apkVersion: <ACE_CONNECT_APK_VERSION>,
})
```

If `unresolved` is non-empty for any recipe, halt with `[BLOCKER]`
naming:

- the logical selector names that didn't resolve
- the recipe(s) that referenced them
- the active selector-map version (`connect-<apkVersion>.yaml`)
- remediation: `Add missing rows to mcp/mobile/selectors/connect-<apkVersion>.yaml — see PR #249 for the calibration pattern (3 added rows + 5 re-verified for the connect-2.62.0 map). Until that lands, this opp cannot reach Phase 6 cleanly.`

This gate exists because Phase 6's `app-screenshot-capture` will
block on the same condition when it tries to run the recipes against
a live AVD. Shifting it left to Phase 3 — where Nova `get_form` /
`get_app` context is still in-scope — gives the author a chance to
fix the recipe's selector references (or surface the map gap for a
calibration PR) before the unresolved selectors reach the emulator.
Both `leep` and `turmeric` runs in early May 2026 hit this class at
Phase 6; this is the structural preventer.

`unverified` entries are NOT a blocker — they substitute fine, they're
just flagged as not-yet-re-verified against the live APK. Surface the
list as `[WARN]` and continue.

### Step 3.5 (optional): Runtime smoke validator

Static `mobile_validate_recipe` cannot detect brief-vs-live label drift
(see Step 3). The runtime smoke validator catches it by attempting each
`is_smoke: true` recipe against a live AVD and confirming every
`tapOn:text` matcher resolves on a real screen.

**Run only when the operator has mobile bootstrap healthy and opts in.**
Set `--smoke-validate` to enable; default is OFF so non-mobile-bootstrapped
operators can run Phase 3 to completion without an AVD. When the flag is
set:

1. Confirm bootstrap health via `mobile_ensure_avd_running()`. If it
   returns `running: false` and the AVD can't auto-start, log
   `[INFO] smoke validator skipped: AVD unavailable` and continue —
   don't fail Phase 3 over a dev-machine state issue.
2. For each `is_smoke: true` journey's recipe, call:

   ```
   mcp__plugin_ace_ace-mobile__mobile_run_recipe({
     recipe_path: <path/to/journey-<app>[-<slug>].yaml>,
     dry_run_selectors: true,   // resolve every selector, don't actuate
     env_vars: { OPP_NAME, ... },
   })
   ```

3. If `dry_run_selectors: true` returns any unresolved `tapOn:text`
   matcher, halt with a `[BLOCKER]` naming the offending recipe + step
   + the missing string. The fix is usually to swap the brief label
   for the live `get_form`-derived label per Step 3.

This is a deferred fix — `mobile_run_recipe` doesn't ship a
`dry_run_selectors` mode today. Until it does, this step is a no-op
warning. Tracking: jjackson/ace#115 finding 2.

### Step 4: Emit the consolidated yaml

Write `ACE/<opp>/runs/<run-id>/3-commcare/app-test-cases.yaml` per the
template in `templates/app-test-cases-template.yaml`. **The path is
`3-commcare/`, NOT the run root** — it must match the Products section
above and the artifact manifest (`lib/artifact-manifest.ts`), which is
what `verify_phase_artifacts(phase=commcare)` checks at the Phase 3
boundary fence. Writing it to the run root passes the skill's own
self-eval (Step 5 lists the file by name) but fails the boundary fence
with `missing: 3-commcare/app-test-cases.yaml`. Reproducer:
malaria-itn-app/20260529-1124 — the master yaml landed at the run root
and the orchestrator had to `drive_move_file` it into `3-commcare/`.

### Step 5: Self-evaluate coverage

(Same shape as pdd-to-test-prompts.) Verify:
- Every journey from `pdd-to-app-journeys.md` has a binding
- Exactly one `is_smoke: true` per app
- **Learn-module completeness — `journey-learn.yaml` MUST finalize EVERY learn-module-bearing form (jjackson/ace#897).** Connect gates Deliver on `learn_progress == 100%` — a `CompletedModule` for **every** `connect.learn_module` marker — and a module only registers when the form carrying its block is **finalized/submitted** on-device (`form_receiver/processor.py::process_learn_modules`). So a Learn smoke recipe that walks the assessment + only *some* content forms leaves Learn stuck below 100% and Deliver permanently locked (canonical: hh-poverty-targeting/20260722-1341 — 4/5 modules, 80%, Deliver locked, mis-blamed on the platform). **Assert:** read the Learn app via `get_app`, collect the set of forms carrying a `connect.learn_module` block, and confirm `journey-learn.yaml` finalizes **every one of them** (each is walked to submit — `content-form-finish[-to-suite]` or a quiz answer+`form-submit`, not skipped). The count of module-forms the recipe finalizes MUST equal the number of `connect.learn_module` markers. If any module-bearing form is not finalized by the recipe, the walk cannot reach 100% — fix the recipe before writing `app-test-cases.yaml` (do not ship a Learn smoke that structurally can't complete Learn). Phase 6's runtime Connect-learn-completion gate (`app-screenshot-capture`) is the backstop that catches a partial completion live; this static check prevents authoring one.
- Exactly one `is_smoke: true` per app
- **Two-app coverage invariant.** For any opp with both a Learn and a
  Deliver app (every archetype except a hypothetical Learn-less mode),
  `smoke_journeys_per_app.learn` MUST be `1` AND
  `smoke_journeys_per_app.deliver` MUST be `1`. **Do not write
  `app-test-cases.yaml` with `learn: 0` "because Phase 2 didn't
  produce a Learn journey"** — halt instead with a `[BLOCKER]` naming
  Phase 2 (`pdd-to-app-journeys`) as the remediation target. The
  Phase 6 pre-flight reads this field; emitting `learn: 0` produces
  a silent downstream halt with no Learn-app screenshots in the
  training deck. Caught in vivo on malaria-itn-app run 20260517-1829;
  Phase 2 contract tightened in the same PR.
- **Exactly the SMOKE recipes exist as files; deep journeys carry
  `recipe: deferred`.** Confirm via `drive_list_folder` against the
  recipes folder — the file count must equal the number of
  `is_smoke: true` journeys (normally 2: `journey-learn.yaml` +
  `journey-deliver.yaml`). Do NOT require deep-journey recipe files to
  exist at Phase 3 — they are generated on demand by `/ace:qa-deep` (see
  § Products + jjackson/ace#605). For each non-smoke journey, assert the
  catalog entry's `recipe:` is the literal `deferred` (not a path and not
  an authored file). Phase 6's `app-screenshot-capture` reads only the
  smoke recipes from this folder; a missing SMOKE recipe silently
  degrades the deck-build to placeholder screenshots
  ([#106 finding 3](https://github.com/jjackson/ace/issues/106) — the
  leep-paint-collection run hit this exact gap and required two
  manual `/ace:step` retries to recover).
- **Date-default static gate — every smoke-walked form
  (dimagi-internal/ace#1081).** The date widget defaults to today, so a
  required `kind: date` field whose `validate` rejects today is
  un-walkable UNLESS the recipe drives it with the APK's calibrated
  mechanism (§ `kind: date` questions; `datePickerDriveFor(apk)` —
  2.63.2 tap, 2.64.0 fling per ace#2518) — and without this gate that is
  discovered on the emulator in Phase 6, not here.

  **"Defaults to today" is TRUE ONLY ON A FIRST VISIT TO A CASE
  (dimagi-internal/ace#1982).** A `kind: date` field that is ALSO a case
  property is preloaded by Nova on a repeat visit, exactly like the
  attendance, participation and geopoint fields the AS-FOUND screenshots
  already capture — so it arrives holding the PREVIOUS visit's date, not
  today's, and a recipe that "just advances past it" files the old date
  as the new meeting's date. **On any journey that returns to an existing
  case, a case-bound date field MUST be explicitly driven or explicitly
  asserted; never advanced past on the default-is-today assumption.**

  Live on `spark-facilitator/20260828-0703`. `journey-deliver-followup-preload`
  carried the comment *"group `Meeting date` — default (today) satisfies
  `. <= today()`. Not driven."* and advanced. Three meetings walked on
  01 Sep each submitted `date_of_meeting = 2026-08-29` — the device clock
  was correct (`timeEnd` = 01 Sep on all three), and `date_of_meeting` is
  a case property carrying `2026-08-29`. `last_meeting_date` is
  `calculate`d from `date_of_meeting`, so the case's "Last meeting"
  column never advanced, and the deep app-UX verdict opened with a
  BLOCKER reading *"the community case's durable state does not advance
  on a real meeting"* — a defect in the harness reported as a defect in
  the product.

  The cost of the wrong attribution is the point: that BLOCKER drove a
  `reject` disposition and two rounds of investigation into a case-write
  path that was working correctly the whole time. For each
  form a smoke recipe walks (`forms_exercised`), feed the form's fields
  (from `get_form`: `id`, `kind`, `required`, `validate`) through the
  pure helper:

  ```ts
  import { checkDateDefaultValidate, formatDateDefaultValidateReport }
    from '../../lib/date-default-validate';
  const report = checkDateDefaultValidate(fields);
  ```

  - A `verdict: 'violated'` row → **`[BLOCKER]` naming the field** (its
    `fieldId` + the `validate` expression, via
    `formatDateDefaultValidateReport`): the recipe cannot advance past
    that screen as-is. Remediation options, in order: drive the field
    one step with the APK's calibrated mechanism immediately before the
    advance (2.64.0: `dayStepFlingYaml()`, ace#2518) when one step
    satisfies the constraint; rebind the journey to a
    branch that avoids the field (record which branch and why — the
    payable-path coverage loss must be explicit, per ace#1081's
    spark-facilitator repro); otherwise halt — the field needs the
    ace#1081 selector-map calibration (live-device work) before it is
    walkable. Never ship a recipe that `form-advance`s into the
    constraint error.
  - A `verdict: 'unverifiable'` row → `[WARN]` naming the field and the
    reason; confirm by hand that today satisfies the expression before
    shipping the recipe. Never treat unverifiable as a pass.
- **Transition criteria must assert a DELTA, not presence
  (dimagi-internal/ace#1885).** A criterion whose *name* claims a state
  transition — `updated`, `changed`, `advanced`, `incremented`,
  `decremented`, `refreshed`, `moved`, `cleared`, `reset`, `increased`,
  `decreased` — MUST be verified by an assertion that could only hold
  AFTER the transition. An assertion that would pass identically before
  and after it is not a test of the transition: the test cannot fail for
  the reason it exists. Canonical failure: on
  `spark-facilitator/20260828-0703`, `journey-deliver-followup-preload`
  declared `case_state_updated_after_submit` and the generated recipe
  asserted it as `assertVisible: { text: "Chilanga.*", childOf: { id:
  "${SELECTOR:case-list-container}" } }`. That proves the **row exists**.
  Behind it sat a real `blocks-e2e` defect — three submitted-and-synced
  meetings dated 01 Sep did not advance Chilanga's `last_meeting_date`
  (stale at 08:40, 08:49 and 09:00) while the control case Nsanje Central
  updated correctly in the same frame, and Connect reported
  `delivered: 4`. **The harness went green;** only the screenshot judge
  caught it, after the fact.

  Exactly two shapes count as proof, and the check is mechanical:

  1. **A captured-pair comparison.** A capture step (`copyTextFrom`, or
     an `evalScript` that writes `output.*`) BEFORE the transition, and a
     later `assertTrue`/`assertFalse` whose expression reads that
     capture. This is the only shape that observes both sides.
  2. **A declared expected NEW value.** Write the criterion as
     `{ name: <criterion>, expected_value: <the new value> }` in
     `structural_pass_criteria` and assert that literal in the recipe.
     The literal must NOT also be a navigation target earlier in the
     recipe — a string the recipe TAPPED to get here is on screen before
     the transition too, so asserting it proves nothing.

  **Run the gate before writing `app-test-cases.yaml`** (and again in
  `/ace:qa-deep` when a deferred deep recipe is generated), feeding it
  each journey's criteria plus its composed recipe steps in file order:

  ```ts
  import { checkTransitionCriteria, formatTransitionCriteriaReport }
    from '../../lib/transition-criteria';
  const report = checkTransitionCriteria(journeys);
  ```

  Every violation is a `[BLOCKER]` naming the journey, the criterion and
  the assertions the recipe does carry (via
  `formatTransitionCriteriaReport`). Fix the recipe — or, if the delta
  genuinely cannot be observed on-device, RENAME the criterion to what it
  actually checks (`case_row_present_after_submit`) and record the lost
  coverage. Never leave a transition-named criterion standing on a
  presence assertion; that is the ace#1885 silent green.
- **Multi-day criteria are declared, not discovered (dimagi-internal/ace#2670).**
  Some criteria on a `longitudinal-visits` app need **more than one dated
  record on the SAME case**, for example "the 4th meeting is labelled not
  paid" or "savings shown only from step 5". If the date field's `validate`
  is strictly increasing (`. > date(#form/prev_...)`) AND capped at
  `<= today()`, a case takes at most one such record per device-day. When
  the anchor is also stamped `today()` at registration (an `enrolment_date`
  hidden `calculate: today()`), a case registered today takes exactly one.
  A one-day backward drive is now calibrated (`dayStepBackFling`,
  ace#2785), but whether `/ace:qa-deep` may back-date records to reach them
  is undecided (commands/qa-deep.md Stage B step 4), so those criteria
  stay unreachable inside one `/ace:qa-deep` session. Back-dating a
  SINGLE field the journey itself asks for (e.g. "Day 1 = yesterday")
  is a different thing and is allowed, with the read-back assert above.

  For each deep journey criterion, check this when cataloguing it, and
  again when `/ace:qa-deep` composes the deferred recipe. Read the
  `validate` of every date field the criterion's records pass through
  (`get_form` / `get_field`). If reaching the criterion needs N > 1 records
  on one case under such a constraint, write it in the mapping form
  `{ name, reachability: multi-day, reason }`. The reason must name the
  field, the constraint and N. Classify each `validate` with
  `detectMultiDayDateConstraint` from `lib/criterion-reachability.ts`
  (`multiDay: true` = strictly after a prior record AND capped at
  `today()`); `normalizeCriterion` refuses a multi-day entry without a
  reason. Spacing advice in a catalog note is not a
  declaration, because no downstream step reads notes. Canonical case:
  `spark-facilitator/20261004-1706`, where `date_of_meeting` validates
  `. <= today() and ... (#form/prev_meeting_date = '' or . > date(#form/prev_meeting_date))`.
  `fourth_meeting_labelled_not_paid` and `savings_shown_only_from_step_5`
  were reached by nothing and declared by nothing. Do not split the journey
  to dodge the declaration. The criterion is the coverage, and losing it
  silently is the failure.
- Every authored (smoke) recipe passes `mobile_validate_recipe`
- Every authored (smoke) recipe's `mobile_resolve_selectors` pass returned
  `unresolved: []` (Step 3.4 gate; non-empty means the APK selector
  map is missing rows and Phase 6 will block). Deep journeys
  (`recipe: deferred`) are not checked here — `/ace:qa-deep` runs the
  same gate when it generates them.
- Every `forms_exercised` entry resolves to a real Nova form ID
- **No `composition_status` (or any composition-escape field) on any
  `is_smoke: true` journey entry.** Per § Step 2's closed-escape rule,
  the `composition_status` field is banned entirely. With the split
  model (Learn-to-completion + Deliver-resume), composition is the
  default path — the old "monolith or BLOCKER" binary is gone.
  Writing any `composition_status` value is a contract violation;
  reject pre-write; never tolerate.

**If any check fails, halt with a `[BLOCKER]` in `auto_surfaced`.**
Do NOT write `app-test-cases.yaml` until the recipe coverage matches
the `is_smoke` count (smoke recipes authored as files; deep journeys
carried as `recipe: deferred`). This is a pre-write structural gate — no
verdict file is emitted (no LLM-as-Judge in this skill; the deep UX
judging happens later in `app-ux-eval`).

## Mode behavior

- Auto: write everything, halt on blocker
- Review: pause to show the journey→form bindings before composing recipes
- Dry-run: write the yaml + journey bindings; stub recipe paths; state
  tracks as `dry-run-success`

## Failure modes

- **Any `mobile_run_recipe` failure → read the forensics first.** On a recipe
  `status: 'fail'` (or a thrown driver-death failure, where the artifacts ride
  on `error.failureForensics`), Read `failureForensics.screenshotPath` (the
  failure screen) + `failureForensics.uiDumpPath` (the element tree) before
  writing a verdict or escalating — the screen usually names the failure mode
  literally. Canonical contract: `playbook/integrations/mobile-integration.md
  § Failure forensics`; full failure-mode table in `app-screenshot-capture`.
- pdd-to-app-journeys.md missing or empty → Phase 1 hasn't completed; halt
- Nova blueprint missing for one of the apps → Phase 3 build hasn't
  succeeded; halt with pointer to upstream skill
- mobile_validate_recipe rejects more than 2× per journey → escalate
  with the validator output

## MCP tools used

- ace-gdrive: drive_read_file, drive_create_file, drive_create_folder
- ace-mobile: mobile_resolve_selectors, mobile_validate_recipe
- nova: get_app

## Decisions Log

**Review fields (schema v6 — REQUIRED).** The decisions log is the run's review artifact (the build memo is retired). Every row this skill appends carries `plain` — one plain-language line for a programme partner who has never seen ACE — and, where the choice is visible somewhere a reviewer can open, `check_at` + `correct_looks_like`. This skill's rows are ACE's own test harness: send `audience: internal` (the atom stamps it on `test-*` / `*smoke*` ids anyway); internal rows need no `plain`. The atom rejects a partner-facing row without `plain`, or with jargon in it. Rules, a worked row and the `review_ask` semantics: [`skills/_decisions-review-fields.md`](../_decisions-review-fields.md); field contract: `docs/decisions-contract.md`.

This skill writes load-bearing defaults to the per-run
`ACE/<opp-name>/runs/<run-id>/decisions.yaml`. The bar criterion and
schema live in `skills/idea-to-pdd/SKILL.md § Decisions Log Convention`
(canonical authority). The list below catalogs decisions that commonly
qualify under the bar for this phase — a working template, not a
required set. The skill applies the bar criterion and emits whatever
rows meet it; the catalog is a teaching device that improves over time.

### Common load-bearing decisions for Phase 3

| ID | Question | Map to surface |
|---|---|---|
| `test-scenario-count` | How many app-walkthrough scenarios feed the qa+eval pair? | `pdd-to-app-journeys-eval` coverage_completeness dimension |
| `test-archetype-coverage` | Are all archetypes in the PDD covered by at least one scenario? | `pdd-to-app-journeys-eval` archetype_alignment dimension |

The orchestrator's Phase Write-Back Verifier (`agents/ace-orchestrator.md`
§ Phase Write-Back Contract § Decisions log clause) enforces the
contract; the renderer (`skills/decisions-render`) regenerates the gdoc
at end of every phase.

Each row this skill writes uses `phase: 3-commcare` and
`skill: app-test-cases`. The convention is the phase the skill is
dispatched in, not the phase its outputs are consumed in — this skill is
dispatched from `agents/commcare-setup.md § Step 2.6` even though
`app-test-cases.yaml` + per-journey recipes are consumed by Phase 6's
`app-screenshot-capture`. Aligns with the artifact manifest, which
already maps the producer to `3-commcare/` (see
`lib/artifact-manifest.ts`).

## Change log

| Date | Change | Author |
|------|--------|--------|
| 2026-10-01 | **`content-form-finish*` loops are bounded — pre-advance the excess (closes dimagi-internal/ace#2574).** § Multi-screen content forms claimed both finalize recipes "subsume the single-screen and the multi-screen cases"; they are unrolled loops of 12 / 14 guarded `nav_btn_next` slots, and Nova now builds lessons as one top-level label per screen. spark-facilitator/20261001-2208's Learn app had lessons of 20 and 15 label screens against the 14-slot `-to-suite` loop, so composed as prescribed they could never finalize (Learn <100%, Deliver locked). The section now states the slot table and prescribes `S - N` bare `form-advance` steps before the call. *Enforced:* `recipe-sanity-probe` class `content-form-finish-overrun` + the slot-count lock in `test/mcp/mobile/recipe-sanity-probe.test.ts`. | ACE team |
| 2026-09-27 | **The ace#1081 next-cell tap is a no-op on APK 2.64.0 — drive the date picker with a one-row fling (dimagi-internal/ace#2518).** spark-facilitator/20260926-1413 Phase 6: Maestro reported the relational tap `COMPLETED`, the picker stayed on today, and `. > today()` refused FINISH. Of four candidates probed on the same form (ui-dump read-back), only a one-row upward swipe on the day column (529,968 → 529,818, 600 ms) moved 27 → 28. § `kind: date` questions now carries a per-APK drive table; the fling is emitted from `lib/date-picker-drive.ts` `dayStepFlingYaml()` (element-relative derivation from the day column's cell bounds — Maestro 2.5.1 cannot anchor a bounded swipe on an element). *Enforced:* `recipe-lint` rule `date-picker-next-cell-tap-noop` rejects the relational tap for 2.64.0 (`test/mcp/mobile/recipe-lint.test.ts`), and `test/lib/date-picker-drive.test.ts` pins the helper to the observed pixels. | ACE team |
| 2026-09-05 | **A case-bound date field does NOT default to today on a repeat visit (closes dimagi-internal/ace#1982).** The Step 5 date-default gate's premise — "the date widget defaults to today" — holds only on a FIRST visit. Nova preloads a `kind: date` field that is also a case property, so on a follow-up journey it arrives holding the previous visit's date, and a recipe that advances past it files the old date as the new meeting's. Live on `spark-facilitator/20260828-0703`: `journey-deliver-followup-preload` declared the date "Not driven", and three meetings walked on 01 Sep each submitted `date_of_meeting = 2026-08-29` with a correct device clock. Because `last_meeting_date` is calculated from it, the case's Last-meeting column never moved and the deep app-UX verdict opened with a BLOCKER blaming the product's case-write path — which was working correctly throughout. A journey returning to an existing case must now drive or assert a case-bound date field explicitly. | ACE team |
| 2026-09-01 | **A transition criterion must assert a DELTA, not presence (dimagi-internal/ace#1885).** Step 5 gains a static gate: a criterion whose NAME claims a state transition (`updated`, `changed`, `advanced`, `incremented`, `refreshed`, `moved`, `cleared`, …) must be verified either by a captured-pair comparison (`copyTextFrom` / `evalScript` before, `assertTrue` reading it after) or by a declared `expected_value` the recipe asserts and never taps. Earned by `spark-facilitator/20260828-0703`, where `journey-deliver-followup-preload` declared `case_state_updated_after_submit` and asserted it as `assertVisible "Chilanga.*"` — proof the ROW EXISTS, not that the date moved — and went green over a real `blocks-e2e` defect (`last_meeting_date` stale across three synced meetings while a control case updated in the same frame). The test could not fail for the reason it existed. *Enforced:* `lib/transition-criteria.ts` + `test/lib/transition-criteria.test.ts`, whose calibration fixture is that exact criterion and assertion. | ACE team |
| 2026-08-29 | **Every emitted `- inputText` must be immediately preceded by `- eraseText` (closes dimagi-internal/ace#1844).** Maestro's `inputText` appends at the cursor rather than replacing, so any field carrying a Nova casedb preload (ace#1809), an XForm default, or a stray character received the recipe's value concatenated onto the existing one. Live on `spark-facilitator/20260828-0703` Phase 6 (ACE 0.13.1080, APK 2.63.2): the recipe typed `40` into `hh_represented_at_the_meeting`, the field held `140`, the form's cross-field constraint correctly refused to advance, and the leg died two screens later on a Participation scroll — reading as a selector fault it was not. Re-running the identical leg with `eraseText` inserted before each of the 6 `inputText` calls passed end-to-end (`{delivered: 1, approved: 1, rejected: 0}`). The dangerous half is that wherever the concatenation does NOT trip a constraint the corruption is silent and the leg reports `pass` on wrong data. *Enforced:* `recipe-sanity-probe`'s new `input-without-erase` — pure recipe shape, so unlike its field-gated siblings it runs unconditionally, and unlike them it carries no false-positive tax (a redundant erase on an empty field is a runtime no-op). `findInputFocusSteps` now sees through the interposed `eraseText`, so the ace#1554 checks don't go silently dead on recipes authored under the new rule. | ACE team |
| 2026-08-25 | **Learn suite re-entry is selected PER FORM, not per app, and the call is guarded (closes dimagi-internal/ace#1633).** § Suite re-entry between modules picked the finalize/re-entry pair from a single per-APP reading of `post_submit`, but where a `previous` finalize lands is a property of the OWNING MODULE: CommCare auto-skips a module's one-row form list when the module holds exactly one form whose name differs from the module name, so `previous` lands on the suite ROOT there and on the form LIST everywhere else. One app can be both shapes at once — `bednet-check-2-visit/20260825-1310` (module "Baseline check": one form "What you know now"; module "Spot-check training": two forms; all `post_submit: previous`) — and the per-app table then prescribes an unconditional `back` that walks OUT of the suite after module 1, hanging the walk before module 2 (the #1071 signature, #897 consequence). The section now states the per-form rule with both module shapes spelled out, and every composition of `learn-suite-reentry-from-module.yaml` is guarded POSITIVELY on the next module's suite row (the workaround that run shipped), which is correct under either landing. The 2x2 stays as the choice of WHICH recipe; the finalize half is landing-agnostic because `content-form-finish-to-suite.yaml` exits on the `learn-suite-menu` alternation. *Enforced:* `test/skills/learn-suite-reentry-guarded.test.ts`. | ACE team |
| 2026-08-23 | **§ Multi-screen content forms now branches on `post_submit` (closes dimagi-internal/ace#1566 — the finalize half of the #1071 class).** The section prescribed `content-form-finish.yaml` unconditionally for every content form while § Suite re-entry between modules already branched, so a multi-module Learn app whose forms are `post_submit: previous` (Nova's default) got a finalize recipe whose bounded advance loop and terminal assert are both keyed on the home-grid `learn-home-start-tile` — a surface that never renders when the finalize lands on the module's own form list. Live: bednet-check-2-visit/20260820-0832 (2 modules, 5 forms, all `previous`). Finalize + re-entry are now stated as one 2x2 (multi/`module` → `content-form-finish` + `learn-suite-reentry`; multi/`previous` → `content-form-finish-to-suite` + `learn-suite-reentry-from-module`; single-module → `content-form-finish-to-suite`, no re-entry). Enforced by `test/mcp/mobile/static-recipe-invariants.test.ts § home-anchored finalize is post_submit-gated`. | ACE team |
| 2026-05-04 | Initial version. Phase 3 producer for app-test-cases.yaml; binds pdd-to-app-journeys.md to Nova-built structure with Maestro recipe stubs. Successor to qa-plan (retired in same release). | ACE team |
| 2026-05-08 | Add `## Decisions Log` section: 2 anchor rows (test-scenario-count, test-archetype-coverage) + bar-criterion reference. Pairs with decisions-log PR #4 (Phase 3-10 writes). | ACE team (decisions-log PR #4) |
| 2026-05-22 | Fix `phase:` tag in Decisions Log footer: was `6-qa-and-training` (the consuming phase), now `3-commcare` (the dispatching phase, matching the artifact manifest's existing `3-commcare/` path mapping). Follow-up to issue #399. | ACE team |
| 2026-05-12 | Add Step 3.4 — recipe-wide `mobile_resolve_selectors` gate. Halts `[BLOCKER]` on any unresolved logical selector before recipes are written to Drive. Shifts left a class of Phase 6 blockers (leep + turmeric runs both hit this in early May) to Phase 3, where Nova form/field context is still in-scope. Follows PR #249's `connect-2.62.0.yaml` calibration. | ACE team |
| 2026-05-22 | Add § Quiz / required-input answer-tap rule — MANDATORY. Forbids `${SELECTOR:radio-first-option}` and other generic-positional placeholders; mandates per-required-field answer steps (literal `tapOn: text:` from Nova `get_form` options) before `form-advance.yaml`. Closes the malaria-rdt run 20260522-1002 Phase 6 BLOCKER class: both smoke recipes chained `form-advance` across required quiz questions with zero answer-selection steps, stalling on `warning_root`. Step 3.4's selector-resolution gate already catches the positional-placeholder half; this section adds the author-side rule that prevents emission in the first place. | ACE team |
| 2026-05-27 | Recipe naming convention: `J<n>.yaml` → `journey-<app>[-<slug>].yaml` (smokes use bare `journey-learn`/`journey-deliver`). `id: J<n>` retained as internal key. Screenshot labels `sc-J<n>-*` → `<recipe-base>-*`. See spec 2026-05-27-phase6-learn-deliver-decoupling. | ACE team |
| 2026-05-27 | Deliver-smoke composition: split the 80-step Learn-re-walk monolith into journey-learn (walks Learn to completion) + journey-deliver (resumes from unlocked state via connect-resume-opp -> deliver-launch). Closes the leep 20260527 J2 deferral class — composition is now the default, BLOCKER reserved for genuinely un-composable structures. | ACE team |
| 2026-05-29 | Fix Step 4 output-path bug: was `ACE/<opp>/runs/<run-id>/app-test-cases.yaml` (run root), contradicting the Products section + artifact manifest (`3-commcare/app-test-cases.yaml`). The run-root write passed the skill's own Step 5 self-eval but failed the Phase 3 boundary fence's `verify_phase_artifacts(commcare)` with `missing: 3-commcare/app-test-cases.yaml`. Step 4 now writes to `3-commcare/` and calls out the mismatch explicitly. Reproducer: malaria-itn-app/20260529-1124 (orchestrator had to drive_move_file the master yaml into 3-commcare/). | ACE team |
| 2026-05-31 | **Meaningful journey ids.** Journey `id` in `app-test-cases.yaml` is now a short intent-derived kebab-case slug (`learn-happy-path`, `learn-wrong-retry`, `deliver-yes`, `deliver-no`, `deliver-multi-visit`, `deliver-gated-on-learn`) instead of the cryptic `J<n>` ordinal — so run artifacts, screenshot labels, smoke-subset lists, and verdicts all read meaningfully and pair with the descriptive recipe filenames. Added § Journey id convention; updated every example/snippet, the template, the fixture, and downstream readers (`app-screenshot-capture`, `app-ux-eval`). Recipe filenames already descriptive (2026-05-27); this completes the convention by making the ids themselves meaningful. | ACE team |
| 2026-05-31 | **`journey-` prefix on every journey id.** Amended the convention so the `id` now carries the literal `journey-` prefix (`journey-learn-pass`, `journey-learn-retry`, `journey-deliver-submit`, `journey-deliver-alt-answer`, `journey-deliver-multiple`, `journey-deliver-locked`) — `id = journey-<app>-<intent>`, always starting with `journey-` — so the id is self-describing wherever it is listed. Recipe *filenames* are unchanged (still `journey-<app>[-<slug>].yaml`; smokes still `journey-learn.yaml` / `journey-deliver.yaml`); the doc now states the filename-vs-id distinction explicitly. Producer + downstream readers (`app-screenshot-capture`, `app-ux-eval`, `app-test-cases-template.yaml`, `ACE-Test-001` fixture) updated. (follow-up to PR #597) | ACE team |
| 2026-05-31 | **Intent-based journey-id slugs (replace answer-value names).** Renamed the canonical intent slugs from answer-value names to test-intent names — the learn smoke is now `journey-learn-pass`, learn retry `journey-learn-retry`, the deliver smoke `journey-deliver-submit`, the alternate-answer journey `journey-deliver-alt-answer`, the multi-visit journey `journey-deliver-multiple`, and the gate-locked journey `journey-deliver-locked`. The old slugs named a raw domain answer value (e.g. a literal `yes`/`no` response), which is meaningless unless you already know the question and doesn't generalize across opps; the intent names describe the behavior being verified, so they read clearly for any opportunity (bednet, vaccination, anything). The `journey-` prefix rule, the `journey-<app>-<intent>` shape, and the filename-vs-id nuance (PR #603) are all unchanged. Example/canonical slug rename only — no lazy-generation / deep-recipe-timing changes. Updated every example/snippet here plus downstream readers (`app-screenshot-capture`, `app-ux-eval`), `app-test-cases-template.yaml`, and the `ACE-Test-001` fixture. | ACE team |
| 2026-05-31 | **Lazy deep-recipe generation (closes #605).** Phase 3 now authors Maestro recipe files ONLY for the two `is_smoke: true` journeys; every non-smoke (deep) journey stays in the `app-test-cases.yaml` catalog with `recipe: deferred` (the literal string, not a path). Phase 6 (shallow, in `/ace:run`) only ever walks the smokes, so pre-authoring deep recipes was wasted work + clutter when `/ace:qa-deep` isn't run. `/ace:qa-deep` now generates the deferred deep recipes on demand using the SAME composition rules here (static palette + live `get_form` labels + selector-resolution gate) — safe because Nova `app_id` + `get_form` still return the as-built structure within a run. Step 3 scoped to "smoke journeys"; Step 5 coverage invariant changed from "every journey has a recipe file" to "exactly the smoke recipes exist as files; deep journeys carry `recipe: deferred`" (two-app smoke invariant + selector-resolution gate for the smokes KEPT). Updated `commands/qa-deep.md`, `app-screenshot-capture`, `app-test-cases-template.yaml`, and the `ACE-Test-001` fixture. | ACE team |
| 2026-07-30 | **Add § answer-tap rule step 4.7 (`kind: date`) + the Step 5 date-default static gate (the static half of dimagi-internal/ace#1081).** The date widget defaults to today, so `<= today()` / `>= today()` constraints need no interaction — but a strictly-future/past constraint has NO calibrated selector (the connect-2.63.2 map carries no date-widget row), so today violating the constraint makes the screen un-walkable. New pure helper `lib/date-default-validate.ts` (`checkDateDefaultValidate`) statically evaluates each required date field's `validate` with `.` = today; Step 5 now BLOCKER-gates a violation naming the field (and WARNs on unverifiable expressions) at Phase 3 instead of burning Phase 6 wall-clock (spark-facilitator/20260730-1718 repro: `next_meeting_date` with `. > today() and . <= date(today() + 30)` silently rerouted the Deliver smoke to the non-payable branch). The selector-map date-widget row itself stays open on ace#1081 pending live-device calibration. | ACE team |
| 2026-08-01 | **Close dimagi-internal/ace#1138 Gap 2 — the followup/case-select leg.** New `mcp/mobile/recipes/static/deliver-case-select.yaml` + four live-calibrated case-list rows in `connect-2.63.2.yaml` (`case-list-container`, `case-list-header`, `case-list-row-cell`, `case-list-detail-continue`), captured from a real `EntitySelectActivity` ui-dump on ACE_Pixel_API_34 / CommCare 2.63.2 (spark-facilitator/20260731-0656). `deliver-form-walk.yaml` now composes the case handoff BETWEEN Level 1 and Level 2 — CommCare collects the case BEFORE the form (module -> case list -> detail CONTINUE -> form list -> form), and the detail screen is a real screen the walk must cross. Authors bind `CASE_NAME`; the `[BLOCKER]` halt for followup-only payable forms is retired. Also fixes a latent defect in Gap 1's shipped recipe: the Level-1 positional fallback guarded only on `notVisible: ${MODULE_NAME}`, which flips TRUE once the named branch navigates away, so it fired on the case list and died on `row_txt` not found. Enforced by four new invariant blocks in `test/mcp/mobile/static-recipe-invariants.test.ts` (positive-guard rule, container-scoped case tap, detail-CONTINUE crossing, handoff ordering), each proven non-vacuous. | ACE team |
| 2026-07-31 | **The leading-label rule is now STATICALLY ENFORCED (closes dimagi-internal/ace#1045); nested `runFlow.env` finally feeds the module/form checks (closes #1068).** § Quiz / required-input answer-tap rule → "Leading (and interior) display/label screens" had been prose-only since #710/#684, and recurred in that window (bednet-spot-check/20260729-0002: a golden `journey-learn.yaml` tapped a q1 option with no advance past the `intro` label, killing the Learn leg and locking Deliver). `recipe-sanity-probe` gained `answer-tap-before-leading-label-advance` — counts the walked form's leading `kind: label` nodes (skipping `hidden`) and fails when fewer bare advances sit between the menu-walk entry step and the first answer tap, naming expected vs found. It's the inverse of the #858 permissive carve-out and is field-gated like `group-field-list-per-question-walk`. Same PR taught `extractRecipeParameters` to walk NESTED `runFlow.env` maps (the shape Phase 3 emits), so `expected-module-not-in-app` / `expected-form-not-in-module` can fire at all — they had been silently inert — plus a `module-form-checks-not-run` WARN + `observed.module_form_checks_ran` so an inert check never reads as a clean pass. Still prose-only: the score-gated over-advance class (#569). | ACE team |
| 2026-07-31 | **Menu anchors are display-mode-agnostic; a single-container anchor is now a CI failure (closes dimagi-internal/ace#1127).** #1082/PR #1100 correctly made Phase 3 `app-hq-settings` apply GRID menu display app-wide — and because every Phase 6 menu anchor resolved to the LIST container `screen_suite_menu_list` ALONE, no shipped palette recipe could execute on any ACE opp (bednet-spot-check/20260731-1353: Learn halted at `learn-launch.yaml`, Deliver walled identically, Phase 6 `verdict: blocked`, apps confirmed healthy server-side). CommCare renders the SAME `row_img`/`row_txt` rows in either container; only the container id changes. Fix: `learn-suite-menu` / `deliver-suite-menu` are now regex alternations (`org.commcare.dalvik:id/(screen_suite_menu_list|grid_menu_grid)`) in connect-2.63.0 + 2.63.2, `deliver-form-walk.yaml`'s two RAW container literals now route through the map, and a new `menu-container anchors are display-mode-complete` invariant suite fails on (a) any palette file hardcoding a container id, (b) any selector-map row naming one container but not all, (c) any RESOLVED palette anchor that isn't complete. Adding a future display mode = one id in `KNOWN_MENU_CONTAINERS` + one map edit. | ACE team |
| 2026-06-01 | **Learn content forms are multi-screen + finalize to StandardHomeActivity (closes #646).** Two new static palette pieces: `content-form-finish.yaml` (bounded multi-screen advance loop that taps `nav_btn_next` until a Learn CONTENT form auto-finalizes, exits on the `learn-home-start-tile` home anchor — NOT the suite menu — handles the score-gated two-screen FINISH, and asserts the home grid post-finalize) and `learn-suite-reentry.yaml` (the explicit "tap Start → wait `screen_suite_menu_list`" re-entry that MUST run between every module, because a Learn form finalizes to the home grid not the suite menu). Added §§ "Multi-screen content forms" + "Suite re-entry between modules"; the prior single-screen-only content-form note is subsumed. Closes the malaria-rdt/20260601-0929 Phase 6 Learn-walk blocker (recipe walked each content form as single-screen and called the next `learn-tap-module` directly, stalling on page 2 then hard-failing the suite-menu assert). Validated structurally (`mobile_validate_recipe` + selector-resolution gate against connect-2.63.0); full live re-walk lands on the next fresh-run Phase 6 (this run consumed its one-way Learn state). | ACE team |
| 2026-08-01 | **Migrated Nova reads to uuid addressing (ace#1132).** Nova's 2026-07-31 redeploy moved its whole surface from `moduleIndex`/`formIndex`/`fieldId` to `moduleUuid`/`formUuid`/`fieldUuid`. Two `get_form` reads here named uncallable operations — § Use live labels passed a bare `form_id`, and the per-form-walk field read in § Emitting a form-walk segment passed the index pair — both rejected server-side with `unrecognized_keys`. Both now pass `{app_id, moduleUuid, formUuid}`, resolved ONCE from `get_app({app_id})` (its blueprint prints `[uuid …]` on every module, form, and field), with `search_blueprint({query, app_id})` for a single semantic name. Enforced by `test/skills/nova-uuid-addressing.test.ts`. | ACE team |
| 2026-08-20 | **Sanction the hint-anchored focus tap ace#1299 actually validated (closes ace#1547).** PR #1397 closed ace#1299 COMPLETED but left § Step 3 item 3 declaring both replacement idioms un-emittable until proven on a live device, 14 hours after that issue's own follow-up comment proved the hint-anchored one on-device (isolated probe, `spark-facilitator/20260813-2126`: `cbf_name` and `phone_number` landed in their OWN fields). Read literally, that made any Deliver field-list with more than one text input unauthorable — Step 2.6 halts `[BLOCKER]` and Phase 6 gets zero Deliver screenshots (observed on `hh-poverty-targeting/20260819-1435`). Item 3 now carries the validated rule (**the focus anchor is the element immediately above the `EditText` — the field's `hint` when it has one, the question label when it does not**), the validated idiom, and the guarded-vs-unconditional discriminator: guarded when the anchor IS the tap target (ace#1070 stands for option taps), unconditional when the anchor is a DIFFERENT element from the tap target, because there `when: notVisible: <anchor>` is structurally blind to the real failure ("anchor visible, its EditText still below the fold"). `speed: 30` replaces `speed: 80` in the option snippet — at 80 the centring scroll overshot a ~300px radio band and halted the leg (ace#1299). Index-based anchoring stays uncalibrated. Same reconciliation applied to `docs/mobile-atlas/connect-2.63.2.md` § 1, `mcp/mobile/selectors/connect-2.63.2.yaml` (`form-question-input*` prose), and the `group-field-list-per-question-walk` remediation string in `mcp/mobile/recipe-sanity-probe.ts`, which still taught the inert bare `below:` tap. Pinned by `test/mcp/mobile/static-recipe-invariants.test.ts § app-test-cases field-list input focus contract`. | ACE team |
| 2026-08-23 | **Both halves of the § group-field-list item-3 input rule are now STATICALLY ENFORCED (closes ace#1554).** ace#1299 § 4 specified two checks and called them explicitly unit-testable; neither had landed, because `NovaFieldSlice` carried no `hint` — `grep -n "hint" mcp/mobile/recipe-sanity-probe.ts` returned exactly one hit, prose inside a remediation string. So the probe returned a clean `ok: true` with `field_data_supplied: true` on the very recipe that produced `cbf_name = "Thandiwe Banda0991234567"` with a required `phone_number` empty. `recipe-sanity-probe` gains `input-anchor-skips-hint` (a focus tap anchored on the QUESTION LABEL of a hint-carrying field — the anchor resolves to the hint TextView and the tap moves no focus) and `input-focus-scroll-is-guarded` (a `when: notVisible: <anchor>` wrapper around the centring scroll, structurally blind to "anchor visible, its EditText still below the fold" — ace#1299's "more important half"), plus `hint?: string` on `NovaFieldSlice` and `observed.hint_data_supplied`. Filed un-bundled from ace#1547/PR #1553 precisely because a false positive here halts Phase 3 in an `incomplete` re-author loop, so both checks default to SILENCE under uncertainty: the hint check reads only fields that positively carry a `hint` (missing hints ⇒ no-op, never an assumed "no hint"), an ambiguous anchor attributes to nothing (the ace#1548 rule), a hint-less field anchored on its label is CORRECT and never flagged, and the guard check fires only on the `tapOn: below:` + `inputText` shape, never on an option tap where ace#1070 keeps the guard right. Step 2.6's caller must now pass `hint` alongside `label` (omit the key when there is none). Pinned by 22 cases in `test/mcp/mobile/recipe-sanity-probe.test.ts`, half of them "does NOT flag". | ACE team |
| 2026-09-06 | **Stop routing concerns to a gate brief that does not exist (dimagi-internal/ace#1884).** 0.13.116 removed the per-skill gate-brief file class and the ace#1880 sweep removed the remaining `*.md` PATHS, but prose directives naming the gate brief as a DESTINATION survived in 15 files — a concern "surfaced in the gate brief" is surfaced nowhere. Repointed at the verdict YAML's `auto_surfaced` block, which is what the orchestrator actually renders the pause summary from. Gated by the new destination check in `test/skills/gate-brief-removal-complete.test.ts`. | ACE team |
| 2026-10-16 | **Field-list option taps scroll to the OPTION, not by position (dimagi-internal/ace#2186).** § Step 3 item 2's ace#1814 rule — scroll to the question label, `centerElement` `false` for every question but the last — was generalised from one run's layout and stranded a MIDDLE question's options below the fold (`poverty-graduation/20260905-1345`, MILK, question 3 of 4; again on `smallholder-seasonal/20261012-1549`). Item 2 now emits a `centerElement: false` label scroll followed by a scroll to the option itself, scoped `below:` the label, `visibilityPercentage: 100`, `centerElement: false` — the form both runs passed with (dispatch `1788810583478-glxovg`, 7 pairs; `20261012-1549`, 21 taps). Also documents that the ace#1070 option-centring guard stacked on a `below:`-anchored tap evicts the label on a long option list (`Chikwawa`, option 7 of 28), and fixes the `unguarded-option-tap-below-long-label` remediation string, which taught a label scroll its own check rejects. | ACE team |
| 2026-10-05 | **Multi-day criteria are declared (dimagi-internal/ace#2670).** Step 5 now requires `{name, reachability: multi-day, reason}` on any deep-journey criterion that needs N > 1 dated records on one case under a strictly-increasing, `<= today()` date `validate`. One `/ace:qa-deep` session cannot reach such a criterion, and the 2.64.0 picker has no calibrated backward drive. `/ace:qa-deep` records it NOT REACHED and `app-ux-eval` lists it under `not_reached`. Earned by `spark-facilitator/20261004-1706` (`fourth_meeting_labelled_not_paid`, `savings_shown_only_from_step_5`). | ACE team |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall