SPOT-004: one search-scope calling convention — file, dir, and ext scopes alike in the PATH slot

Now: OPEN

Design ticket, ordered by gritzko 2026-07-19 ("think of improving the calling convention for file-scoped and dir-scoped and ext-scoped alike"). Today only the ext scope works: be spot ".js#'a = null'" searches the .js family, but a FILE scope (spot "shared/branch.js#'…'") dies with SPOTNOEXT and grep-mode's file scope is SILENTLY ignored (verified 2026-07-19: grep:shared/branch.js#null scanned the whole tree, 4684 lines starting at core/discover.js). Extend the SPOT-003 path-slot ruling into one uniform grammar: [mode:][scope]#locator, scope any of file / dir / ext / dir+ext, fragment = locator only.

Input

Context

Ruling in force (SPOT-003, 2026-07-18): scope rides the PATH slot, never the fragment; spot:.c#'…' = ext family, spot:/root/path#'…' = subtree with per-file grammar; the fragment-.ext form is dead.
Code today (views/spot/search.js): q.ext is set only when the WHOLE path is a bare .ext (:59); the spot gate mode==="spot" && !q.ext → SPOTNOEXT (:256) predates the ruling; a real path never confines the classify walk (grep evidence above); trail .ext args don't rescue a pathed first arg.
The locator side is DONE: SPOT-002's shared/spot.js parses all four fragment syntaxes (#L123, #needle, #/re/, #'pat'); SPOT-003's index gates by path — both compose with any path-slot scope.
Error texture on misses is the BE-003 class (bare SPOTNOEXT, uri.parse: malformed on a spaced bare arg).

Goals

Proposed convention (pending gritzko's ruling): the ONE arg is [mode:][scope]#locator; the scope path resolves via resolve(context,base,rel) like every verb arg, then classifies by what it names:

empty scope → whole worktree, each file parsed with its OWN grammar;
.ext (bare extension segment) → that lexer family, whole tree;
a FILE path → exactly that file, grammar from its own ext — no explicit .ext ever required;
a DIR path → that subtree, per-file grammar;
dir/.ext (dir prefix + .ext final segment) → subtree AND family filter — bare .ext is just this form at the root.
SPOTNOEXT retires: a structural locator over a file with no known lexer SKIPS that file (a plain-words note), never a fatal; a nonexistent scope path errs in plain words.
All three modes (spot/grep/regex) obey the same scope rules — grep's silent whole-tree fallback becomes a red leg.

Constraints

Scope resolution through resolve(context,base,rel)/core resolve only — verbs resolve args, the pager stays arg-blind; no manual path/URI surgery.
Fragment stays locator-only (SPOT-003 ruling); the four syntaxes come from SPOT-002 shared/spot.js — no second parser.
Joins the blocked SPOT-003 TODOs (parseURI scope + search.js candidates/gate wiring) — one wiring pass once SPOT-002/003 land; /wiki/View.mkd §"Search views" gets the hand edit then.

WIP

Design decisions

Pending gritzko's ruling on the Goals grammar (esp. dir/.ext composition and the skip-not-fail rule for unknown lexers under spot mode).

TODOs

red: file scope confines (spot + grep), dir scope confines, dir/.ext composes, unknown-lexer skip note, plain-words miss — legs per mode.
scope classifier in search.js parse (file/dir/ext/dir+ext) off the resolved path; SPOTNOEXT gate removed.
wire the classify walk to the scope (and SPOT-003 gate when it lands); suite at baseline.

Blockers and bummers

Lands after SPOT-002/SPOT-003 merge (same search.js seam); until then this is the design ground.

Outcome

Pending.