Fix: verify touch gestures in adapt, audit, and harden (#805) (#807)

* Fix: verify touch gestures in adapt, audit, and harden (#805)

The verification sections of adapt.md, audit.md, and harden.md listed
environments and layout properties but never had the agent exercise a
control's primary gesture, so an emulated viewport plus screenshots
could pass as touch testing. adapt now exercises the primary gesture
and the scroll-across trade and reports what produced the evidence,
audit checks broken touch interaction with code-level tells, harden
covers interrupted gestures and recovery, and a reference-contract
test pins the three sections.

Prepared with AI assistance (Claude Code), directed by @abdulwahabone.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Pin the scroll, exercise, and cleanup sentences in the reference test (#805)

Greptile flagged that the contract test pinned the new labels but not
adapt's scroll-across trade, audit's instruction to exercise the
gesture, or harden's drag-state and capture cleanup.

Prepared with AI assistance (Claude Code), directed by @abdulwahabone.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

skill/reference/adapt.md

@@ -188,6 +188,12 @@ Test thoroughly across contexts:
 - **Edge cases**: Very small screens (320px), very large screens (4K)
 - **Slow connections**: Test on throttled network
 
+**Custom controls** (sliders, drag surfaces, scrollable control strips): a before/after slider can pass every width check above and still refuse to drag on iOS, so exercise each one in scope in the same batched round as the checks above:
+
+- **Primary gesture**: Tap it and confirm it responds as designed, then drag it with the target input method; the drag must complete, not just start
+- **Scroll across it**: A swipe along the page's scroll axis across the control scrolls the page or container without activating it; a drag that starts on the control along its axis moves the control, not the page. Neither failure throws an error, so try both
+- **Evidence**: Say what produced the evidence: an emulated viewport, synthesized touch input through a browser tool, which engine ran it (Chromium is not Safari), or a physical device. Screenshots and resized viewports verify layout, never a gesture. Name what stayed untested and move on; unreachable hardware is a reported gap, not a blocker
+
 When the adaptation feels native to each context, hand off to `{{command_prefix}}impeccable polish` for the final pass.
 
 ---

skill/reference/audit.md

@@ -48,11 +48,12 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the
 **Check for**:
 - **Fixed widths**: Hard-coded widths that break on mobile
 - **Touch targets**: Interactive elements < 44x44px
+- **Broken touch interaction**: Custom sliders, drag surfaces, and scrollable control strips whose primary gesture fails under touch, that swallow page scroll or lose the drag to it, or that stay stuck after an interrupted gesture. Code tells: mouse-only handlers, no `touch-action` on a pointer-event drag surface, drag state that nothing clears on cancel, lost capture, or blur. Exercise the gesture when a browser tool can synthesize touch (a rendered viewport proves layout, not the gesture), then say what produced the evidence (emulated viewport, synthesized touch, which engine, physical device) and what stayed untested
 - **Horizontal scroll**: Content overflow on narrow viewports
 - **Text scaling**: Layouts that break when text size increases
 - **Missing breakpoints**: No mobile/tablet variants
 
-**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets)
+**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets, gestures work under touch)
 
 ### 5. Implementation Integrity (CRITICAL)
 

skill/reference/harden.md

@@ -205,6 +205,11 @@ t('items', { count }) // Handles complex plural rules
 - Optimistic updates with rollback
 - Conflict resolution
 
+**Interrupted gestures** (custom sliders, drag surfaces, scrollable control strips):
+- A second finger or pointer lands mid-drag: the first drag keeps its pointer or ends cleanly, never jumps to the new one
+- The browser cancels the gesture to scroll (`pointercancel`), capture is lost (`lostpointercapture`), the pointer is released outside the control, or the window loses focus (`blur`) mid-drag: clear the dragging state and release capture
+- After each of these, the next tap or drag works without a reload
+
 **Permission states**:
 - No permission to view
 - No permission to edit
@@ -304,6 +309,7 @@ const throttledScroll = throttle(handleScroll, 100);
 - Unit tests for edge cases
 - Integration tests for error scenarios
 - E2E tests for critical paths
+- A behavioral regression for each confirmed gesture fix, when the project's test runner can drive input
 - Visual regression tests
 - Accessibility tests (axe, WAVE)
 
@@ -330,7 +336,10 @@ Test thoroughly with edge cases:
 - **Network issues**: Disable internet, throttle connection
 - **Large datasets**: Test with 1000+ items
 - **Concurrent actions**: Click submit 10 times rapidly
+- **Interrupted gestures**: Add a second finger mid-drag, scroll across the control, release outside it, switch windows mid-drag; then drag again
 - **Errors**: Force API errors, test all error states
 - **Empty**: Remove all data, test empty states
 
+For gestures, say what produced the evidence (emulated viewport, synthesized touch, which engine, physical device) and name what stayed untested.
+
 When edge cases are covered, hand off to `{{command_prefix}}impeccable polish` for the final pass.

tests/skill-reference.test.mjs

@@ -67,4 +67,26 @@ describe('skill reference authoring contracts', () => {
     assert.match(polish, /if a newer critique landed meanwhile, its backlog stays live/);
     assert.doesNotMatch(polish, /git status|git log/);
   });
+
+  it('keeps touch-gesture verification in the adapt, audit, and harden references', () => {
+    const adapt = readFileSync(join(ROOT, 'skill/reference/adapt.md'), 'utf-8').replace(/\r\n?/g, '\n');
+    const audit = readFileSync(join(ROOT, 'skill/reference/audit.md'), 'utf-8').replace(/\r\n?/g, '\n');
+    const harden = readFileSync(join(ROOT, 'skill/reference/harden.md'), 'utf-8').replace(/\r\n?/g, '\n');
+    const verifyAdaptations = adapt.match(/## Verify Adaptations\n([\s\S]*?)\n## /)?.[1] ?? '';
+    const responsive = audit.match(/### 4\. Responsive Design\n([\s\S]*?)\n### 5\./)?.[1] ?? '';
+    const edgeCases = harden.match(/### Edge Cases & Boundary Conditions\n([\s\S]*?)\n### /)?.[1] ?? '';
+    const verifyHardening = harden.match(/## Verify Hardening\n([\s\S]*?)(?:\n## |$)/)?.[1] ?? '';
+
+    assert.match(verifyAdaptations, /\*\*Primary gesture\*\*/);
+    assert.match(verifyAdaptations, /produced the evidence/);
+    assert.match(verifyAdaptations, /verify layout, never a gesture/);
+    assert.match(verifyAdaptations, /reported gap, not a blocker/);
+    assert.match(verifyAdaptations, /\*\*Scroll across it\*\*[\s\S]*without activating it/);
+    assert.match(responsive, /\*\*Broken touch interaction\*\*/);
+    assert.match(responsive, /what stayed untested/);
+    assert.match(responsive, /Exercise the gesture when a browser tool can synthesize touch/);
+    assert.match(edgeCases, /\*\*Interrupted gestures\*\*[\s\S]*works without a reload/);
+    assert.match(edgeCases, /clear the dragging state and release capture/);
+    assert.match(verifyHardening, /\*\*Interrupted gestures\*\*/);
+  });
 });