Description
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
apex-sentinel-staging commentedon Nov 13, 2026
Apex Sentinel · Issue review
Suggested label:
bugThe issue points to a concrete mismatch: CLI help for
scroll --untilpromises a visible-tree fallback, butanalyzeScrollEdgeStatereportedly stops withcanScroll: falsewhen no scroll container is found. It gives actionable fixes, either reword the help or implement the promised fallback with a test.Required sections
thymikee commentedon Nov 16, 2026
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.
thymikee commentedon Nov 16, 2026
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.