You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
help semantics: document behavioral guarantees, not just command shapes #1051
Several load-bearing behaviors lived as tribal knowledge until this week, and in two cases the maintainers' own mental model differed from the code: selector ambiguity (believed always-fail; actually deepest-then-smallest auto-disambiguation, ties fail — documented only now via #1040), hittability semantics on iOS, runner retention across close (#557-era behavior surprised everyone in #1021's review), idle-stop lifetimes, session/device binding rules. Agents reason from guarantees; when guarantees are undocumented they probe with real commands instead — token waste and flaky conclusions.
Expectation
A help semantics topic (or a "Guarantees" section in help workflow) covering: selector ambiguity policy + failure string; hittability meaning and the targetHittable signal; what open/close/relaunch guarantee about app and runner state (including retention + idle stop, kill switches); ref lifetime (cleared by open/relaunch); snapshot freshness/diff semantics; wait semantics. One screen, statements-of-fact style, kept in sync by doc-assertion tests like the one #1040 added. Acceptance: each statement traceable to code, at least three covered by doc-assertion tests.
Activity
feat(help): document behavioral guarantees in help workflow (#1051) (#…