docs(adr): describe Maestro endpoint-hold internal seam in ADR 0013/0015

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: thymikee

docs/adr/0013-unified-gesture-plans.md

@@ -22,22 +22,31 @@ the Android planned-touch executor.
 ## Decision
 
 Public gesture inputs normalize once in `src/contracts/gesture-normalization.ts`. This is the
-explicit compatibility boundary: convenience APIs and deprecated arguments become canonical
-semantic intent before entering the runtime. The private daemon wire is free to evolve with that
-model; compatibility is owed at CLI, Node.js, and MCP.
+explicit public compatibility boundary: canonical semantic intent is produced before entering the
+runtime. Deprecated arguments that have been removed (timed `swipe`, timed `gesture fling`,
+`gesture rotate` `velocity`) are rejected with actionable `INVALID_ARGS` messages rather than
+silently reinterpreted. The private daemon wire remains free to carry compatibility-only hints
+that do not appear on public surfaces; Maestro timed swipes use
+`internal.gestureExecutionProfile: 'endpoint-hold'` to preserve iOS fast-swipe-then-hold behavior
+while still routing through the canonical `pan` input.
 
 The runtime plans canonical intent in `src/contracts/gesture-plan.ts`. Contact topology is separate
 from motion:
 
 - one contact: pan or fling with a complete pointer trajectory and an explicit execution profile;
 - two contacts: pan, pinch, rotate, or transform with two complete, synchronized trajectories.
 
-`swipe` without a duration is public sugar for a fixed-duration fling. Its historical optional
-duration normalizes to pan intent with an endpoint-hold execution profile and reports a deprecation
-toward explicit pan. Maestro-authored swipes follow the same normalization and materialize
-Maestro's 400 ms default when duration is omitted. A genuine pan uses the timed-pan profile, so
-compatibility aliases retain their release behavior without becoming a new semantic intent. The
-same deprecation-to-pan rule applies to the historical fling duration. Pinch fixes translation and rotation at zero; rotate fixes
+`swipe` without a duration remains public sugar for a fixed-duration fling. Timed public forms
+(`swipe x1 y1 x2 y2 durationMs`, `gesture fling direction x y distance durationMs`,
+`gesture swipe preset durationMs`, and `gesture rotate degrees x y velocity`) are rejected; callers
+must use `gesture pan` for deliberate timed translation and `gesture rotate` without `velocity`.
+Maestro-authored swipes normalize to the canonical `pan` input (origin, delta, durationMs) and carry
+the `endpoint-hold` execution profile through a daemon-internal compatibility seam
+(`internal.gestureExecutionProfile`). This preserves the iOS fast-swipe-then-hold behavior that
+matches Maestro's XCTest driver, without exposing the profile on the public command surface. Maestro
+materializes its 400 ms default when duration is omitted. A genuine public `pan` uses the `timed-pan`
+profile, so compatibility-only paths retain their release behavior without becoming a new semantic
+intent. Pinch fixes translation and rotation at zero; rotate fixes
 translation at zero and scale at one; two-finger pan fixes scale at one and rotation at zero;
 transform can apply all three
 components atomically. Intent remains on the plan even when aliases share an executor.

docs/adr/0015-direct-maestro-engine.md

@@ -21,7 +21,11 @@ Android compatibility is materially faster than native Maestro in the pager and
 that advantage is a product constraint, not expendable migration headroom.
 
 ADR 0013 separately owns public gesture normalization, contact topology, trajectory planning, and
-native injection. Maestro's supported gesture surface is single-pointer swipe only.
+native injection. Maestro's supported gesture surface is single-pointer swipe only. Maestro swipes
+normalize to ADR 0013's canonical `pan` input (origin, delta, durationMs) and carry the
+`endpoint-hold` execution profile through a daemon-internal compatibility seam
+(`internal.gestureExecutionProfile`), preserving iOS fast-swipe-then-hold behavior without exposing
+the profile on the public command surface.
 
 ## Decision
 
@@ -55,13 +59,17 @@ The engine does not implement platform input. Absolute and percentage swipes pre
 endpoints without a hierarchy capture. Directional horizontal swipes reuse ADR 0013's shared in-page
 preset geometry so an iOS right swipe does not become an interactive-back gesture; vertical presets
 retain Maestro's platform geometry. All viewport-relative swipes resolve the cheapest fresh interaction
-viewport available so ADR 0013 can validate every planned sample.
+viewport available so ADR 0013 can validate every planned sample. Maestro swipes pair that resolved
+viewport with `internal.gestureExecutionProfile: 'endpoint-hold'` on the nested public `gesture` request
+so ADR 0013 produces the iOS fast-swipe-then-hold profile without a public `executionProfile` field.
 When normalization already resolves a viewport, the adapter pairs it with the nested public gesture
 request as daemon-internal metadata. ADR 0013 planning consumes that exact frame instead of probing
 the platform a second time.
+
 Target-relative swipes reuse the target-resolution observation. The resulting typed single-pointer
-motion enters ADR 0013 after public compatibility normalization. Maestro code cannot construct or
-execute two-pointer pan, pinch, rotate, transform, or physical pointer trajectories.
+motion enters ADR 0013 as the canonical `pan` input, with the `endpoint-hold` execution profile carried
+as daemon-internal metadata. Maestro code cannot construct or execute two-pointer pan, pinch, rotate,
+transform, or physical pointer trajectories.
 
 Simple successful target queries return their match, visibility decision, candidate count, and
 observation generation in one response. The daemon may retain the provider snapshot behind that