Fragment-review UI — surface new sub_aspect bindings on WatchedItem detail (diff-on-view)

[gregoryfoster]

Context

The InfoItem-first design (Section 5.3 of docs/plans/2026-05-15-watched-item-infoitem-first-design.md) called for a "diff-on-view" UI on each WatchedItem detail page:

When Archiver gains a new sub_aspect binding under an InfoItem the operator has subscribed to, the WatchedItem detail page surfaces 'N new sub_aspects available' and a one-click 'add Watches for these' action.

The watched_items.last_reviewed_at column was added in commit 57307ad for this purpose but currently has no UI surface.

Scope

On the WatchedItem detail page (forthcoming via #161):

1. Detect new bindings. On render, call archiver.get_info_item(info_item_id) and partition info_item_sources by created_at:
   • Bindings with created_at > watched_item.last_reviewed_at are "new since last review."
   • If none, show "All sub_aspects reviewed" status.
2. Review prompt. Surface "N new sub_aspects available" banner with:
   • Per-binding row (selector, role, created_at).
   • Bulk "Add Watches for these" action that creates Watches with sensible defaults (resolved via the live-inheritance chain).
   • "Mark all reviewed" action that stamps last_reviewed_at = now without creating Watches.
3. Audit log entries for add_watch_from_review and mark_reviewed so the operator can trace why Watches were created.

Acceptance

• WatchedItem detail page shows "N new sub_aspects available since YYYY-MM-DD" when Archiver added bindings after last_reviewed_at.
• Operator can bulk-create Watches for any subset and the action is auditable.
• Operator can mark-reviewed without creating Watches (signal "I've seen these and chose not to watch").
• "Mark reviewed" stamps last_reviewed_at = now atomically.

Depends on

• WatchedItem CRUD UI — edit shared defaults from the dashboard #161 — WatchedItem CRUD UI. The fragment-review surface lives on the WatchedItem detail page introduced there.

Related

• InfoItem-first Watch model: WatchedItem, Watch reshape, two-step picker #160 — InfoItem-first Watch model (this issue is a follow-up captured in the design doc's "Out of scope" + Implementation plan).

[gregoryfoster]

Scope update — caching layer + surface move

The Aspect Review column has been removed from the Watched Items list view in #173 (per-row live Archiver calls on every page render aren't worth it).

The fragment-review surface should move to the WatchedItem detail page, but behind a cache so it doesn't add a live Archiver round-trip to every detail page load.

Proposed caching approach

• Cache store: Redis (already in the stack via REDIS_URL)
• Cache key: aspect_review:{watched_item_id}
• Cache value: {"new_count": int, "checked_at": ISO8601} — number of bindings with created_at > watched_item.last_reviewed_at
• TTL: 1 hour (new sub_aspects are rarely added; operators can live with hour-old data)
• Population: lazy on detail page render — if cache miss, call Archiver, write result, serve from cache
• Invalidation: explicit on POST /watched-items/{id}/mark-reviewed (stamps last_reviewed_at and deletes the cache key)

UI surface (WatchedItem detail page)

• Small banner or badge near the InfoItem binding tree section
• "N new sub_aspects available since {last_reviewed_at}" with a link to the full review flow
• If new_count == 0: no banner (or a collapsed/muted indicator)
• Cache miss / Archiver unavailable: suppress the banner gracefully (don't 500)

What this replaces

The original scope had a per-row hx-trigger="load" partial on the list view. That approach is dropped. The detail page + cache approach trades immediacy (up to 1h stale) for a much lower request cost and a more natural home for the action.

Scope adjustment

The bulk "Add Watches for these" action and the per-binding row UI remain in scope as originally written — just now they live behind a cached check rather than a live one.