docs(specs): revise v0.6.2 spec per subagent review (4 Important, 4 Minor)

Reviewer subagent findings applied:
- I-1: hitRanks added to State block (was referenced but undeclared)
- I-2: SearchBar internal api.search(buildFtsQuery(raw), 500) + three
  fire cases for onQueryChange documented
- I-3: composition snapshot case 5 added (searchHits = empty Set)
- I-4: explicit handleSearchResult removal + badge removal listed
- M-1: containerRef + searching + outside-click useEffect removals
- M-3: searchActive definition consolidated (searchHits !== null)
- M-5: sunse* prefix example added
- M-7: stale-search-after-watcher risk documented
- M-8: (foo OR bar) sanitizer behavior clarified (parens stripped
  pre-tokenisation; OR becomes literal token)
- M-4, M-6: vague process note + outdated test comment rephrased

Spec now ready for writing-plans. Subagent re-review deferred since
all findings were applied verbatim from the first-pass review.

Author: utof

docs/superpowers/specs/2026-04-17-v0.6.2-live-faceted-search-design.md

@@ -41,8 +41,7 @@ redundant dropdown preview.
   wildcards only.
 - **Facet counts across the full corpus.** Counts reflect the visible
   result set only (client-side compute from the loaded `files` array).
-  Tracked as a follow-up optimization; file a `needs-web-search` issue
-  if users complain.
+  Tracked as a follow-up issue (file at implementation time).
 - **List cap pagination.** The 100-row cap on `listFilesWithTags` is
   an existing limitation, not introduced here. Files outside the cap
   are not surfaced by search. Tracked as a separate follow-up issue.
@@ -106,13 +105,19 @@ searchHash: string | null           // was v0.6.1's drill-down hack
 
 // NEW:
 searchQuery: string                 // raw user input, lifted from SearchBar
-searchHits: Set<string> | null      // blake3-hash set of matching files; null when no search
-                                    // Set (not array) for O(1) intersection
+searchHits: Set<string> | null      // blake3-hash set of matching files;
+                                    //   null       = no search active (show all / tag-filter only)
+                                    //   empty Set  = search active but zero matches (show empty list)
+                                    // Set (not array) for O(1) intersection.
+hitRanks: Map<string, number>       // hash → BM25 rank; populated alongside searchHits.
+                                    // Used by sortByRank; new Map() when cleared.
 
 // DERIVED (not state; recomputed each render):
 visibleFiles: FileWithTags[]        // composeVisible(files, selectedTagId, searchHits)
 facetCounts: Record<string, number> // computeFacets(visibleFiles)
-searchActive: boolean               // searchQuery.trim().length >= 2 && searchHits !== null
+searchActive: boolean               // searchHits !== null
+                                    // (the MIN_QUERY_LEN=2 guard lives in SearchBar; by the
+                                    //  time App sees a non-null searchHits, the guard passed)
 ```
 
 ### Components
@@ -147,16 +152,20 @@ export function sortByRank(
 - If the whole input is already wrapped in double-quotes → pass through
   verbatim (phrase query).
 - If the input ends with `*` → treat as prefix query, split tokens,
-  wrap last token as `"prefix"*`.
+  wrap last token as `"prefix"*`. Example: `sunse*` → `"sunse"*`.
 - Otherwise: split on whitespace, quote each non-empty token, join with
   space (FTS5 implicit AND).
   - `sunset photos` → `"sunset" "photos"`
   - `it's fine` → `"it's" "fine"` (apostrophes safe inside quotes)
   - `file/path.ext` → `"file/path.ext"` (slashes + dots OK in quotes)
-- Strip any characters that remain parse-unsafe (`"` inside a token, raw
-  parentheses, `-` at the start of a token → FTS5 negation).
+- Strip any characters that remain parse-unsafe BEFORE tokenisation:
+  bare `"` (unpaired), raw `(` / `)`, and leading `-` on a token
+  (FTS5 negation). Then tokenise and quote as above.
   - Honest subset: phrase + prefix + implicit AND. Everything else
     is quoted away.
+  - Example: `(foo OR bar)` → parens stripped → tokens `foo`, `OR`,
+    `bar` → output `"foo" "OR" "bar"` (three implicit-AND tokens;
+    FTS5 OR keyword is lost, but input doesn't parse-error).
 
 **`computeFacets` reducer:**
 ```typescript
@@ -196,14 +205,26 @@ export function composeVisible(
 
 **Changes from v0.6.1:**
 - Remove dropdown render (the `<div role="listbox">` block entirely).
-- Remove local `hits: SearchHit[] | null` and `open: boolean` state.
+- Remove local `hits: SearchHit[] | null`, `open: boolean`, and
+  `searching: boolean` state.
+- Remove `containerRef` + the outside-click `useEffect` that closed
+  the dropdown.
 - Remove `handleHitClick` and `onResultClick` prop.
 - Keep: debounce, MIN_QUERY_LEN=2 guard, clear-button, error swallow.
 - New prop: `onQueryChange(query: string, hits: SearchHit[] | null)`.
   App.tsx uses this to lift `searchQuery` + the hash-set derived from
   `hits` into App state.
-- On query clear (input emptied): fire `onQueryChange("", null)` so App
-  can restore prior sort + full sidebar.
+- **SearchBar still calls `api.search(buildFtsQuery(raw), 500)`
+  internally** — the sanitizer + IPC stay co-located with the input.
+  After the debounce resolves, SearchBar calls
+  `onQueryChange(raw, hits)` to lift the result upward. (Limit raised
+  from 50 → 500 to feed the in-list re-sort.)
+- **Three fire-cases for `onQueryChange`:**
+  1. User typed ≥ MIN_QUERY_LEN and debounce resolved →
+     `onQueryChange(raw, hits)` (hits may be `[]` if nothing matched).
+  2. User typed < MIN_QUERY_LEN (1 char, or cleared to empty) →
+     `onQueryChange("", null)` so App resets `searchHits` to null.
+  3. User clicked clear button → `onQueryChange("", null)`.
 
 ```typescript
 interface SearchBarProps {
@@ -255,8 +276,15 @@ interface TagSidebarProps {
 #### `apps/desktop/src/App.tsx` (MODIFIED)
 
 **State changes:**
-- Remove `searchHash: string | null`.
-- Add `searchQuery: string` and `searchHits: Set<string> | null`.
+- Remove `searchHash: string | null` (line 52 of current App.tsx).
+- Remove `handleSearchResult` function (lines 179–182 of current
+  App.tsx) — it's the exact source of #25 (`setSelectedTagId(null)`).
+- Remove the `✕ search` badge JSX block from the header (lines
+  190–199 of current App.tsx); the SearchBar's own clear button
+  replaces it.
+- Add `searchQuery: string`, `searchHits: Set<string> | null`, and
+  `hitRanks: Map<string, number>` state (all three initialized as
+  `""`, `null`, `new Map()`).
 
 **Effect on mount (unchanged):** `listFilesWithTags(100)` + `listTags()`.
 
@@ -287,9 +315,10 @@ const sidebarTotalCount = searchActive ? visibleFiles.length : files.length;
 ```
 
 **Header JSX change:**
-- Remove the `✕ search` badge (no longer needed; SearchBar's own clear
-  button handles it).
-- `<SearchBar onQueryChange={handleSearchChange} />`
+- Replace `<SearchBar onResultClick={handleSearchResult} />` with
+  `<SearchBar onQueryChange={handleSearchChange} />`.
+- (The `✕ search` badge removal was already listed above under State
+  changes.)
 
 **Sidebar JSX change:**
 - `<TagSidebar ... mode={sidebarMode} totalCount={sidebarTotalCount} counts={facetCounts} />`
@@ -324,8 +353,9 @@ const sidebarTotalCount = searchActive ? visibleFiles.length : files.length;
   - input with slash/dot `a/b.jpg` → `"a/b.jpg"`
   - empty / whitespace-only → `""` (SearchBar's MIN_QUERY_LEN guard
     blocks upstream; test anyway)
-  - adversarial: `"` alone → stripped; `(foo OR bar)` → quoted
-    `"(foo" "OR" "bar)"` (degrades to plain tokens)
+  - adversarial: bare `"` stripped → empty output; `(foo OR bar)` →
+    parens stripped → `"foo" "OR" "bar"` (OR keyword becomes a
+    literal token; documented limitation)
 - `computeFacets`:
   - empty files → `{}`
   - file with no tags → `{}`
@@ -358,18 +388,21 @@ const sidebarTotalCount = searchActive ? visibleFiles.length : files.length;
   - New: `mode="facets" All row count reflects sum of counts`.
   - Existing tests still pass with `mode="all"` default.
 - `App.test.tsx` (MODIFIED):
-  - Existing file-event debounce test: keep, but change mock expectations
-    — no more `list_files_with_metadata`; just `list_files_with_tags`
-    and `list_tags` (already updated in Task 6 / commit `cd55627`).
+  - Existing file-event debounce test: already correct in current code
+    (mock expectations updated in `cd55627`); no change needed.
   - Existing watcher-banner test: keep as-is.
 - `App.compose.test.tsx` (NEW): **composition snapshot test**. Given
   fixture inputs (files, tagId, hits), assert visibleFiles matches an
-  expected snapshot. Pins the exact bug that shipped in v0.6.1. Four
+  expected snapshot. Pins the exact bug that shipped in v0.6.1. Five
   cases:
   1. No search, no tag → all files.
   2. Tag filter only → tag-narrowed.
   3. Search only → hit-narrowed, sorted by rank.
   4. Search + tag → intersected, sorted by rank (the invariant #25 broke).
+  5. Search active but zero hits (`searchHits = new Set()`) → empty
+     visible list, sidebarMode = "facets", facetCounts = `{}`
+     (empty-state branch). Distinct from case 1 (`searchHits = null`,
+     sidebarMode = "all").
 
 ### No Playwright; no Tauri IPC integration test changes (search command's `search_inner` smoke test already exists from I8 fix).
 
@@ -409,6 +442,17 @@ separate `fix(desktop): ...` commits if needed.
 - **Escape only clearing input (v0.6.2) will feel inconsistent when
   the detail view lands** (#27). Explicit v0.6.2 limitation; #28 fixes
   it holistically.
+- **Stale search hits after file-watcher refresh.** `searchHits` is
+  not automatically re-queried when the watcher fires a list refresh
+  (the existing 300ms debounced `listFilesWithTags(100)` reload).
+  After a watcher-triggered reload, if the user was searching, their
+  `searchHits` set still reflects the pre-reload corpus — so new
+  files matching the query won't appear, and deleted files will be
+  filtered out by the missing hash. User-visible as "the list isn't
+  updating even though I know I just added a file." Mitigation for
+  v0.6.2: documented; user can retype to re-fire. Post-v1 fix: the
+  file-event effect in App.tsx re-calls `buildFtsQuery` + `api.search`
+  alongside the `listFilesWithTags` refresh when a search is active.
 
 ## Decisions and why