Skip to content

scroll --until help promises a visible-tree fallback the code does not have #4510

Open

Description

@thymikee

Problem

The scroll --until help (src/commands/schema/cli-help-gestures.ts:24) says: "If no container is found, they compare the visible tree." The code has no such fallback. When a vertical --until search finds no scroll container with a usable rectangle, analyzeScrollEdgeState (packages/capture-kit/src/snapshot/scroll-edge-state.ts) reports canScroll: false with no containerRect, and the loop stops on that instead of comparing the visible tree. An agent that reads the help expects a search that keeps going on screens without a detectable container, and gets an early stop instead.

The sentence arrived in #4407 (dc8e320, 2026-11-11).

Fix

Make the help and the code agree. Either:

  • reword the sentence to say what happens: with no detectable scroll container, the search stops after the first pass and reports why; or
  • add the fallback the sentence promises (compare signatures of the whole visible tree), with a test for a screen that has no scrollable node.

Rewording is the smaller change unless there is evidence that container-less screens are common.

Why it shipped

#4407 passed review, including the maintainer's review pass, which verified each behavior claim in the PR body against the code. It did not verify the new help sentence: help and doc text were treated as non-blocking wording, and nothing compares help claims with the code.

Guards

  • Review (done): the maintainer's review pass now traces every added or changed sentence of CLI help and user docs that states what a command does to the code path that does it, and treats a promise the code does not keep as blocking.
  • Repo docs: add the same rule to docs/agents/review.md, so every reviewer, human or agent, checks help sentences against the code.
  • Static check (proposal): for help strings that describe a fallback or a refusal, pin the claim to a test that drives that branch. A light version is a unit test per command family that asserts each documented refusal reason or fallback mode name appears both in the help text and in the code's typed reasons.

Activity

  1. apex-sentinel-staging commented on Nov 13, 2026

    @apex-sentinel-staging

    Apex Sentinel · Issue review

    Suggested label: bug

    The issue points to a concrete mismatch: CLI help for scroll --until promises a visible-tree fallback, but analyzeScrollEdgeState reportedly stops with canScroll: false when no scroll container is found. It gives actionable fixes, either reword the help or implement the promised fallback with a test.

    Required sections

    • Steps to reproduce (missing)
    • Expected and actual behavior (missing)
    • Version or environment (missing)
  2. thymikee commented on Nov 16, 2026

    @thymikee
    MemberAuthor

    An agent is picking this up; the PR will link here. This corrects the help and user-doc claims and adds the review rule; no runtime fallback or static prose checker.

  3. thymikee commented on Nov 16, 2026

    @thymikee
    MemberAuthor

    Current state: the original fallback premise here was incorrect. The no-container branch builds a visible-tree fingerprint, and scroll --until uses that fingerprint without treating canScroll:false as a stop. The existing help statement is accurate; no runtime fallback or one-pass stop change is needed. The approved review-guidance addition remains in scope. The candidate gate passed, but publication is held while the coordinator removes unnecessary help edits and finishes that guidance-only change.

  4. added
    documentationImprovements or additions to documentation
    and removed
    bugSomething isn't working
    in-progressWork is actively in progress
    on Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions