feat(similar): cache the team board in ~/.linear-cli/cache.sqlite, synced by updatedAt (PHNX-4105)

[muqsitnawaz]

feature. tasks --similar stops re-fetching the whole team on every run.

Tracking: https://linear.app/getrush/issue/PHNX-4105

What changed

• linear — new # ---- board cache ---- section: cached_team_issues() keeps the team's issues in ~/.linear-cli/cache.sqlite (tables issues + sync, beside vectors). First run fetches everything; later runs add updatedAt: { gt: <last sync> } to the filter and upsert only what moved; a full refresh runs when the last one is older than 7 days so archived issues drop out; --project filters the cached board locally; a failed refresh over a warm cache answers from the cache and prints one stderr line. rank_similar uses it for the lexical and embeddings candidates. EMBEDDINGS_DB_PATH becomes CACHE_DB_PATH; an existing embeddings.sqlite is renamed in place on first open.
• test_linear.py — _IsolatedCache mixin so every test that reaches rank_similar runs against a temp cache; BoardCacheTests (full then incremental, failed refresh, cold failure, local project filter, weekly full refresh, legacy rename); two SimilarTests assertions updated for local project filtering and cache ordering.
• README.md / skill.md / CHANGELOG.md — cache file name and the Unreleased entry.

Verification

Real run against the live board (3,931 issues) with the worktree binary and an isolated temp HOME holding only config.json. Ticket titles are redacted in the capture because this repo is public.

Same run in text: python3 -m unittest → 219 tests OK, 4 skipped; linear tasks --similar "token renewal" --limit 3 cold 15.68 s, then warm 1.07 s and 0.89 s with identical rows; cache.sqlite mode 0600, 13080 KB, 3931 issues, one sync row.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FQ3w5SAvum8nShzmBo21Ar

[muqsitnawaz]

APPROVE — independent non-author review (code-reviewer subagent, session 87d560af, reviewed at 996b3b2; verdict was CHANGES REQUESTED on one blocker, which is fixed in 1b06e81 along with every SHOULD).

Traced by the reviewer: incremental filter and watermark math, aware-datetime full-refresh comparison, no partial cache writes (one commit inside the successful-fetch branch), deterministic row order, legacy rename gated on the new file being absent with vectors surviving, ISSUE_FIELDS carries project { id }, every rank_similar-reaching test class isolated, stderr-only refresh-failed line, only the five owned files changed, no version bump, cost is O(delta) with the _MAX_PAGES rail intact.

Applied in 1b06e81: (blocker) two test cleanups restored the removed EMBEDDINGS_DB_PATH instead of CACHE_DB_PATH, leaving a deleted temp path in place for later classes; (should) watermark is now gte with id upserts so a same-instant update is re-fetched, never skipped; (should) a full refresh that hits the pagination rail keeps the cached board and prints one stderr line instead of overwriting with a truncated board, with a test; (should) the legacy os.replace tolerates a parallel first run; (nice) the comment names team moves as a second drift source. 220 tests OK, 4 skipped.