jarvis/docs/BACKLOG.md

Backlog & status

Source-of-truth tracker. The Gitea issue tracker is currently empty (0 issues) — run scripts/create-issues.sh with a token to populate it. [client] = iOS, [backend] = the platform service on the Docker host, [ci] = build/test.

Status: 🔴 open · 🟡 mitigated client-side (real fix still pending) · 🟢 done.

Backend — data quality (highest priority)

1. 🟡 [backend] F1 mis-classified into tech/finance/politics. No sport category, so F1 (100% F1 sources) scatters across topics: "Monaco Grand Prix…" → tech, "F1 reports 35% CO2…" → finance, "McLaren launch appeal…" → politics. Add a sport/f1 topic and route motorsport sources there. Client mitigation shipped: F1 pill matches clear F1 headlines + a majority of F1 sources, and F1 is excluded from All/Tech/Finance. Backend still mis-tags.
2. 🔴 [backend] Catastrophic over-clustering — unrelated articles merged on a single shared word. Newly confirmed on-device: a story merged a Russian-film-director article + "Who's afraid of Michael Jackson?" + "Chelsea Jackson Roberts" (wellness) — grouped on the surname Jackson. Another merged "Gunfire at Niger airport" + "L.A. County Whiteman Airport crash" + "Niger fintech". Result: wrong headline, summary, topic, and inflated signal. Raise the TF-IDF threshold hard (~0.22 → 0.45–0.55) and require multiple shared distinctive terms / named-entity overlap, with a tight time window. If still over-merging, move to sentence embeddings (all-MiniLM-L6-v2, cosine ≥ ~0.6). Make canonical headline + summary come from the same representative article. No client fix is possible — the story object itself is wrong.
3. 🔴 [backend] Add accurate per-story tags (topic + region). So the client can read tags (sport, uganda, south-africa, …) instead of keyword-guessing. Unblocks #6.
4. 🔴 [backend] Topic-classifier coverage for the 47 feeds. science/world/tech mapping.
5. 🔴 [backend] Freshness score decays from lastUpdatedAt (cluster last touched), not from the actual news event age — old stories never leave the top of the feed. Confirmed live on /api/v1/stories: 13 of the top 20 stories are 5+ days old by firstSeenAt but still score 90+; the #1 story (story_511c67eb064d) has firstSeenAt: 2026-06-17, lastUpdatedAt: 2026-07-09 (21 days later), freshnessScore: 1.0, signal 100. Compounds with #2 (over-clustering): a loose cluster keeps absorbing tangential articles indefinitely (this story's timeline includes "Security forces ready for June 30 marches: Ramaphosa" — unrelated to the football story it's attached to), each attachment resets lastUpdatedAt to now, so the cluster's clock never runs out and its canonical headline drifts to whatever was clustered last (list view showed "South Africa stun South Korea…"; story detail showed "Updated FIFA rankings after Bafana Bafana exit" for the same story_id). Fix: decay freshness from firstSeenAt (or the newest article whose relevance to the cluster core is verified), not from "last touched." Tightening the TF-IDF threshold in #2 should also reduce how often unrelated articles keep a stale cluster's clock alive. Also confirmed the API's own isStale field is unusable as a stopgap — it reads false on every story checked regardless of actual age, so it isn't computed from a real staleness threshold. Client mitigations shipped:
   1. Age display (row meta line, hero card) now reads from firstSeenAt instead of updatedAt, so the UI no longer shows "1 hr ago" on stories that are actually weeks old.
   2. Found that StorySummary.clientRank — an existing time-decay mechanism, already in the codebase specifically to stop stale high-scorers from leading the feed — was itself silently neutralized by this same bug: it computed age from updatedAt, so a fossil's age always read as ~0. Fixed to use firstSeenAt. This isn't new client-side ranking logic; it's un-breaking a pre-existing, intentional one.
   3. Added StorySummary.isFossil (firstSeenAt > 5 days old) as a hard backstop — clientRank's decay is soft (max 20% score penalty) and isn't always enough to overcome a high signalScore alone. Fossils are sunk below current stories in mainStories and makeDigest, so a stale story can never occupy the hero/lead slot even if the server still ranks it #1. They still appear in the feed, just not in the most prominent, most misleading position. Still wrong at the source — the server's own signalScore/freshnessScore ordering (what page 2+, pagination cutoffs, and min_signal filtering all rely on) is unaffected; these are display/ordering patches downstream of it. The real fix is still backend-side.

Backend — features

5. 🔴 [backend] Server-side push for breaking alerts (APNs or ntfy). For breaking-story notifications while the app is closed. Client does local notifications + background refresh only.

Client

6. 🔴 [client] Move interest filters server-side once tags (#3) exist. Today's pills are client-side keyword/headline matches on loaded stories. Refined since: regions match headline-only (no polluted summaries/outlets), regions exclusive, F1 by source majority, East Africa removed.
7. 🔴 [client] SSID-based trusted networks. Needs Access WiFi Information entitlement (device + paid account). Approximated by LAN reachability today.
8. 🔴 [client] Optional in-app WireGuard tunnel. NetworkExtension; entitlement + device. Deferred.
9. 🔴 [client] App icon + launch assets. AppIcon is an empty placeholder.
10. 🔴 [client] Flesh out Latest / Search tabs. Saved is now bookmarks; Latest/Search still minimal.
11. 🔴 [client] Verify hero image loading. AsyncImage vs real feed imageUrls.
12. 🔴 [client] Offline-first polish. Pre-cache top stories.

CI

13. 🔴 [ci] Add unit/UI tests + a test matrix leg. Build matrix compiles, runs no tests.
14. 🔴 [ci] Backend CI build matrix. Python 3.11–3.13 + lint + Docker build/health probe.

---

🟢 Shipped

Signal feed + detail + reader + feed manager · LAN⇄Tailscale connectivity · notifications (morning/evening briefings + breaking alerts) with Open-Meteo weather · device code signing · feed resilience (no blank-on-refresh, ignore cancelled, coalesced WS refresh) · clearer empty states (polling / unreachable+host / offline / caught-up) · deterministic feed order · 6-line summary preview · pinned filters (F1 split out, regions exclusive & headline-matched, Finance/Tech by topic) · swipe actions (short→Save / long→Mark read, right→Share) · read/seen handling (seen-tracking with per-load snapshot, read stories collapse into a "Read" shelf with compact rows, "all caught up" state).