mirror of
https://github.com/callstack/agent-device.git
synced 2026-09-14 20:06:34 +08:00
Michał Pierzchała
40e4b0dd3e
* docs(agents): restore and enforce progressive disclosure * test(maestro): pin typed selector fallback signal * docs(agents): address progressive disclosure review * docs(agents): restore orphaned traps and close guidance-gate bypasses - AGENTS.md: skills carry a minimal start/routing card; command semantics stay in versioned CLI help (the skills contract enumerates two skills by hand, so prose retains ownership for the rest) - testing.md: restore the two local-only XCTest snags CI never hits (unsigned-bundle policy refusal signature + first-run automation permission) - scripts/gate/routing.ts: record GitHub's 300-changed-file path-filter limit at the paths-ignore assertion it bounds - agent-guidance-contract.test.ts: recurse docs/agents so nested guidance cannot evade the byte budgets while the gate stays green
36 lines
2.5 KiB
Markdown
36 lines
2.5 KiB
Markdown
# Selector Capture Reliability
|
|
|
|
Read this before changing selector capture, polling, snapshot caching, or interaction fast paths.
|
|
These are cross-route behavior requirements; their rationale and owning decisions live in ADRs
|
|
0002, 0004, 0005, 0011, 0014, and 0015.
|
|
|
|
- Direct iOS selectors are a narrow fast path for simple one-term selectors and are disabled while
|
|
post-gesture stabilization is pending. A structured selector miss may return to snapshot
|
|
resolution; ambiguity and other runner failures remain failures.
|
|
- Regular selector reads are capture-backed. `@ref` resolves against its authorized ref frame,
|
|
while `get`, `is`, `find`, and `wait` selectors capture through the backend. Polling bypasses the
|
|
snapshot cache, as do active freshness recovery and stabilization.
|
|
- Sparse capture verdicts are observable failures and never replace the session snapshot. Only a
|
|
user-facing snapshot may publish a fallback screenshot; internal polling must not create one
|
|
artifact per attempt.
|
|
- Apple accessibility failures are not proof of an empty UI. Recovery plans may serve regular
|
|
snapshots, while raw and strict paths preserve the failure. Fatal runner evidence invalidates the
|
|
cached target.
|
|
- A recorded XCTest failure after a tap is an ambiguous outcome. Only a usable same-presentation
|
|
capture with a changed accessibility digest may corroborate success; missing, sparse, mismatched,
|
|
or unchanged evidence remains failure.
|
|
- Android helper reuse is not snapshot-result caching. Freshness is short-lived, action-triggered,
|
|
and learned only from route-safe complete observations.
|
|
- Pending interaction outcome retry precedes stabilization; Android freshness recovery composes
|
|
afterward when required. Gesture-like mutations mark stabilization and disable direct iOS
|
|
selector shortcuts while it is pending.
|
|
- Session snapshot writes go through the shared snapshot mutation boundary. Sparse observations and
|
|
empty ref-scoped projections do not overwrite stored evidence.
|
|
- Maestro matching remains snapshot- and policy-owned. Coordinate dispatch uses fresh geometry; an
|
|
exact same-generation iOS target may use atomic selector activation, and a structured live miss
|
|
returns to fresh Maestro resolution. Never add fuzzy matching, synthetic geometry, hierarchy
|
|
heuristics, or error-message classification that changes authored selector meaning.
|
|
|
|
When changing one of these rules, update the relevant ADR, guarantee-matrix cell, contract scenario,
|
|
and TypeScript/Swift parity table rather than describing a new exception here.
|