beads-ui 0.2.0 → 0.3.0

package/app/views/list.js

@@ -1,5 +1,6 @@
-/* global NodeListOf */
 import { html, render } from 'lit-html';
+import { createListSelectors } from '../data/list-selectors.js';
+import { cmpClosedDesc } from '../data/sort.js';
 import { ISSUE_TYPES, typeLabel } from '../utils/issue-type.js';
 import { issueHashFor } from '../utils/issue-url.js';
 // issueDisplayId not used directly in this file; rendered in shared row
@@ -9,7 +10,7 @@ import { createIssueRowRenderer } from './issue-row.js';
 // List view implementation; requires a transport send function.
 
 /**
- * @typedef {{ id: string, title?: string, status?: string, priority?: number, issue_type?: string, assignee?: string, labels?: string[] }} Issue
+ * @typedef {{ id: string, title?: string, status?: 'closed'|'open'|'in_progress', priority?: number, issue_type?: string, assignee?: string, labels?: string[] }} Issue
  */
 
 /**
@@ -18,9 +19,30 @@ import { createIssueRowRenderer } from './issue-row.js';
  * @param {(type: string, payload?: unknown) => Promise<unknown>} sendFn - RPC transport.
  * @param {(hash: string) => void} [navigate_fn] - Navigation function (defaults to setting location.hash).
  * @param {{ getState: () => any, setState: (patch: any) => void, subscribe: (fn: (s:any)=>void)=>()=>void }} [store] - Optional state store.
+ * @param {{ selectors: { getIds: (client_id: string) => string[] } }} [_subscriptions]
+ * @param {{ snapshotFor?: (client_id: string) => any[], subscribe?: (fn: () => void) => () => void }} [issueStores]
  * @returns {{ load: () => Promise<void>, destroy: () => void }} View API.
  */
-export function createListView(mount_element, sendFn, navigate_fn, store) {
+/**
+ * Create the Issues List view.
+ * @param {HTMLElement} mount_element
+ * @param {(type: string, payload?: unknown) => Promise<unknown>} sendFn
+ * @param {(hash: string) => void} [navigateFn]
+ * @param {{ getState: () => any, setState: (patch: any) => void, subscribe: (fn: (s:any)=>void)=>()=>void }} [store]
+ * @param {{ selectors: { getIds: (client_id: string) => string[] } }} [_subscriptions]
+ * @param {{ snapshotFor?: (client_id: string) => any[], subscribe?: (fn: () => void) => () => void }} [issue_stores]
+ * @returns {{ load: () => Promise<void>, destroy: () => void }}
+ */
+export function createListView(
+  mount_element,
+  sendFn,
+  navigateFn,
+  store,
+  _subscriptions = undefined,
+  issue_stores = undefined
+) {
+  // Touch unused param to satisfy lint rules without impacting behavior
+  /** @type {any} */ (void _subscriptions);
   /** @type {string} */
   let status_filter = 'all';
   /** @type {string} */
@@ -36,7 +58,7 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
   // Shared row renderer (used in template below)
   const row_renderer = createIssueRowRenderer({
     navigate: (id) => {
-      const nav = navigate_fn || ((h) => (window.location.hash = h));
+      const nav = navigateFn || ((h) => (window.location.hash = h));
       /** @type {'issues'|'epics'|'board'} */
       const view = store ? store.getState().view : 'issues';
       nav(issueHashFor(view, id));
@@ -54,12 +76,11 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
    * @param {Event} ev
    */
   const onStatusChange = async (ev) => {
-    /** @type {HTMLSelectElement} */
-    const sel = /** @type {any} */ (ev.currentTarget);
+    const sel = /** @type {HTMLSelectElement} */ (ev.currentTarget);
     status_filter = sel.value;
     if (store) {
       store.setState({
-        filters: { status: /** @type {any} */ (status_filter) }
+        filters: { status: status_filter }
       });
     }
     // Always reload on status changes
@@ -73,8 +94,7 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
    * @param {Event} ev
    */
   const onSearchInput = (ev) => {
-    /** @type {HTMLInputElement} */
-    const input = /** @type {any} */ (ev.currentTarget);
+    const input = /** @type {HTMLInputElement} */ (ev.currentTarget);
     search_text = input.value;
     if (store) {
       store.setState({ filters: { search: search_text } });
@@ -87,8 +107,7 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
    * @param {Event} ev
    */
   const onTypeChange = (ev) => {
-    /** @type {HTMLSelectElement} */
-    const sel = /** @type {any} */ (ev.currentTarget);
+    const sel = /** @type {HTMLSelectElement} */ (ev.currentTarget);
     type_filter = sel.value || '';
     if (store) {
       store.setState({ filters: { type: type_filter } });
@@ -106,12 +125,13 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
     }
   }
   // Initial values are reflected via bound `.value` in the template
+  // Compose helpers: centralize membership + entity selection + sorting
+  const selectors = issue_stores ? createListSelectors(issue_stores) : null;
 
   /**
    * Build lit-html template for the list view.
    */
   function template() {
-    /** @type {Issue[]} */
     let filtered = issues_cache;
     if (status_filter !== 'all' && status_filter !== 'ready') {
       filtered = filtered.filter(
@@ -131,6 +151,10 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
         (it) => String(it.issue_type || '') === String(type_filter)
       );
     }
+    // Sorting: closed list is a special case → sort by closed_at desc only
+    if (status_filter === 'closed') {
+      filtered = filtered.slice().sort(cmpClosedDesc);
+    }
 
     return html`
       <div class="panel__header">
@@ -212,40 +236,55 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
   // no separate ready checkbox when using select option
 
   /**
-   * Load issues from backend and re-render.
+   * Update minimal fields inline via ws mutations and refresh that row's data.
+   * @param {string} id
+   * @param {{ [k: string]: any }} patch
+   */
+  async function updateInline(id, patch) {
+    try {
+      // Dispatch specific mutations based on provided keys
+      if (typeof patch.title === 'string') {
+        await sendFn('edit-text', { id, field: 'title', value: patch.title });
+      }
+      if (typeof patch.assignee === 'string') {
+        await sendFn('update-assignee', { id, assignee: patch.assignee });
+      }
+      if (typeof patch.status === 'string') {
+        await sendFn('update-status', { id, status: patch.status });
+      }
+      if (typeof patch.priority === 'number') {
+        await sendFn('update-priority', { id, priority: patch.priority });
+      }
+    } catch {
+      // ignore failures; UI state remains as-is
+    }
+  }
+
+  /**
+   * Load issues from local push stores and re-render.
    */
   async function load() {
     // Preserve scroll position to avoid jarring jumps on live refresh
-    /** @type {HTMLElement|null} */
-    const beforeEl = /** @type {any} */ (
+    const beforeEl = /** @type {HTMLElement|null} */ (
       mount_element.querySelector('#list-root')
     );
     const prevScroll = beforeEl ? beforeEl.scrollTop : 0;
-    /** @type {any} */
-    const filters = {};
-    if (status_filter !== 'all' && status_filter !== 'ready') {
-      filters.status = status_filter;
-    }
-    if (status_filter === 'ready') {
-      filters.ready = true;
-    }
-    /** @type {unknown} */
-    let result;
+    // Compose items from subscriptions membership and issues store entities
     try {
-      result = await sendFn('list-issues', { filters });
+      if (selectors) {
+        issues_cache = /** @type {Issue[]} */ (
+          selectors.selectIssuesFor('tab:issues')
+        );
+      } else {
+        issues_cache = [];
+      }
     } catch {
-      result = [];
-    }
-    if (!Array.isArray(result)) {
       issues_cache = [];
-    } else {
-      issues_cache = /** @type {Issue[]} */ (result);
     }
     doRender();
     // Restore scroll position if possible
     try {
-      /** @type {HTMLElement|null} */
-      const afterEl = /** @type {any} */ (
+      const afterEl = /** @type {HTMLElement|null} */ (
         mount_element.querySelector('#list-root')
       );
       if (afterEl && prevScroll > 0) {
@@ -262,12 +301,10 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
     // Grid cell Up/Down navigation when focus is inside the table and not within
     // an editable control (input/textarea/select). Preserves column position.
     if (ev.key === 'ArrowDown' || ev.key === 'ArrowUp') {
-      /** @type {any} */
-      const tgt = /** @type {any} */ (ev.target);
-      /** @type {HTMLTableElement|null} */
+      const tgt = /** @type {HTMLElement} */ (ev.target);
       const table =
         tgt && typeof tgt.closest === 'function'
-          ? /** @type {any} */ (tgt.closest('#list-root table.table'))
+          ? tgt.closest('#list-root table.table')
           : null;
       if (table) {
         // Do not intercept when inside native editable controls
@@ -279,34 +316,26 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
               tgt.closest('select'))
         );
         if (!in_editable) {
-          /** @type {HTMLTableCellElement|null} */
           const cell =
-            tgt && typeof tgt.closest === 'function'
-              ? /** @type {any} */ (tgt.closest('td'))
-              : null;
+            tgt && typeof tgt.closest === 'function' ? tgt.closest('td') : null;
           if (cell && cell.parentElement) {
-            /** @type {HTMLTableRowElement} */
-            const row = /** @type {any} */ (cell.parentElement);
-            /** @type {HTMLTableSectionElement|null} */
-            const tbody = /** @type {any} */ (row.parentElement);
+            const row = /** @type {HTMLTableRowElement} */ (cell.parentElement);
+            const tbody = /** @type {HTMLTableSectionElement|null} */ (
+              row.parentElement
+            );
             if (tbody && tbody.querySelectorAll) {
               const rows = Array.from(tbody.querySelectorAll('tr'));
               const row_idx = Math.max(0, rows.indexOf(row));
-              const col_idx = /** @type {any} */ (cell).cellIndex || 0;
+              const col_idx = cell.cellIndex || 0;
               const next_idx =
                 ev.key === 'ArrowDown'
                   ? Math.min(row_idx + 1, rows.length - 1)
                   : Math.max(row_idx - 1, 0);
-              const next_row = /** @type {HTMLTableRowElement} */ (
-                rows[next_idx]
-              );
-              /** @type {HTMLTableCellElement|null} */
-              const next_cell = /** @type {any} */ (
-                next_row && next_row.cells ? next_row.cells[col_idx] : null
-              );
+              const next_row = rows[next_idx];
+              const next_cell =
+                next_row && next_row.cells ? next_row.cells[col_idx] : null;
               if (next_cell) {
-                /** @type {HTMLElement|null} */
-                const focusable = /** @type {any} */ (
+                const focusable = /** @type {HTMLElement|null} */ (
                   next_cell.querySelector(
                     'button:not([disabled]), [tabindex]:not([tabindex="-1"]), a[href], select:not([disabled]), input:not([disabled]):not([type="hidden"]), textarea:not([disabled])'
                   )
@@ -323,14 +352,10 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
       }
     }
 
-    /** @type {HTMLTableSectionElement|null} */
-    const tbody = /** @type {any} */ (
+    const tbody = /** @type {HTMLTableSectionElement|null} */ (
       mount_element.querySelector('#list-root tbody')
     );
-    /** @type {NodeListOf<HTMLTableRowElement>} */
-    const items = tbody
-      ? tbody.querySelectorAll('tr')
-      : /** @type {any} */ ([]);
+    const items = tbody ? tbody.querySelectorAll('tr') : [];
     if (items.length === 0) {
       return;
     }
@@ -370,7 +395,7 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
       const current = items[idx];
       const id = current ? current.getAttribute('data-issue-id') : '';
       if (id) {
-        const nav = navigate_fn || ((h) => (window.location.hash = h));
+        const nav = navigateFn || ((h) => (window.location.hash = h));
         /** @type {'issues'|'epics'|'board'} */
         const view = store ? store.getState().view : 'issues';
         nav(issueHashFor(view, id));
@@ -412,6 +437,20 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
     });
   }
 
+  // Live updates: recompose and re-render when issue stores change
+  if (selectors) {
+    selectors.subscribe(() => {
+      try {
+        issues_cache = /** @type {Issue[]} */ (
+          selectors.selectIssuesFor('tab:issues')
+        );
+        doRender();
+      } catch {
+        // ignore
+      }
+    });
+  }
+
   return {
     load,
     destroy() {
@@ -422,46 +461,4 @@ export function createListView(mount_element, sendFn, navigate_fn, store) {
       }
     }
   };
-
-  /**
-   * Update minimal fields inline via ws mutations and refresh that row's data.
-   * @param {string} id
-   * @param {{ [k: string]: any }} patch
-   */
-  async function updateInline(id, patch) {
-    try {
-      // Dispatch specific mutations based on provided keys
-      if (typeof patch.title === 'string') {
-        await sendFn('edit-text', { id, field: 'title', value: patch.title });
-      }
-      if (typeof patch.assignee === 'string') {
-        await sendFn('update-assignee', { id, assignee: patch.assignee });
-      }
-      if (typeof patch.status === 'string') {
-        await sendFn('update-status', { id, status: patch.status });
-      }
-      if (typeof patch.priority === 'number') {
-        await sendFn('update-priority', { id, priority: patch.priority });
-      }
-      // Refresh the item from backend
-      /** @type {any} */
-      const full = await sendFn('show-issue', { id });
-      // Replace in cache
-      const idx = issues_cache.findIndex((x) => x.id === id);
-      if (idx >= 0 && full && typeof full === 'object') {
-        issues_cache[idx] = /** @type {Issue} */ ({
-          id: full.id,
-          title: full.title,
-          status: full.status,
-          priority: full.priority,
-          issue_type: full.issue_type,
-          assignee: full.assignee,
-          labels: Array.isArray(full.labels) ? full.labels : []
-        });
-      }
-      doRender();
-    } catch {
-      // ignore failures; UI state remains as-is
-    }
-  }
 }

package/app/views/new-issue-dialog.js

@@ -10,8 +10,9 @@ import { priority_levels } from '../utils/priority.js';
  * @returns {{ open: () => void, close: () => void }}
  */
 export function createNewIssueDialog(mount_element, sendFn, router, store) {
-  /** @type {HTMLDialogElement} */
-  const dialog = /** @type {any} */ (document.createElement('dialog'));
+  const dialog = /** @type {HTMLDialogElement} */ (
+    document.createElement('dialog')
+  );
   dialog.id = 'new-issue-dialog';
   dialog.setAttribute('role', 'dialog');
   dialog.setAttribute('aria-modal', 'true');
@@ -52,32 +53,34 @@ export function createNewIssueDialog(mount_element, sendFn, router, store) {
 
   mount_element.appendChild(dialog);
 
-  /** @type {HTMLFormElement} */
-  const form = /** @type {any} */ (dialog.querySelector('#new-issue-form'));
-  /** @type {HTMLInputElement} */
-  const input_title = /** @type {any} */ (dialog.querySelector('#new-title'));
-  /** @type {HTMLSelectElement} */
-  const sel_type = /** @type {any} */ (dialog.querySelector('#new-type'));
-  /** @type {HTMLSelectElement} */
-  const sel_priority = /** @type {any} */ (
+  const form = /** @type {HTMLFormElement} */ (
+    dialog.querySelector('#new-issue-form')
+  );
+  const input_title = /** @type {HTMLInputElement} */ (
+    dialog.querySelector('#new-title')
+  );
+  const sel_type = /** @type {HTMLSelectElement} */ (
+    dialog.querySelector('#new-type')
+  );
+  const sel_priority = /** @type {HTMLSelectElement} */ (
     dialog.querySelector('#new-priority')
   );
-  /** @type {HTMLInputElement} */
-  const input_labels = /** @type {any} */ (dialog.querySelector('#new-labels'));
-  /** @type {HTMLTextAreaElement} */
-  const input_description = /** @type {any} */ (
+  const input_labels = /** @type {HTMLInputElement} */ (
+    dialog.querySelector('#new-labels')
+  );
+  const input_description = /** @type {HTMLTextAreaElement} */ (
     dialog.querySelector('#new-description')
   );
-  /** @type {HTMLDivElement} */
-  const error_box = /** @type {any} */ (
+  const error_box = /** @type {HTMLDivElement} */ (
     dialog.querySelector('#new-issue-error')
   );
-  /** @type {HTMLButtonElement} */
-  const btn_cancel = /** @type {any} */ (dialog.querySelector('#btn-cancel'));
-  /** @type {HTMLButtonElement} */
-  const btn_create = /** @type {any} */ (dialog.querySelector('#btn-create'));
-  /** @type {HTMLButtonElement} */
-  const btn_close = /** @type {any} */ (
+  const btn_cancel = /** @type {HTMLButtonElement} */ (
+    dialog.querySelector('#btn-cancel')
+  );
+  const btn_create = /** @type {HTMLButtonElement} */ (
+    dialog.querySelector('#btn-create')
+  );
+  const btn_close = /** @type {HTMLButtonElement} */ (
     dialog.querySelector('.new-issue__close')
   );
 
@@ -194,25 +197,20 @@ export function createNewIssueDialog(mount_element, sendFn, router, store) {
    */
   async function createNow() {
     clearError();
-    /** @type {string} */
     const title = String(input_title.value || '').trim();
     if (title.length === 0) {
       setError('Title is required');
       input_title.focus();
       return;
     }
-    /** @type {number} */
     const prio = Number(sel_priority.value || '2');
     if (!(prio >= 0 && prio <= 4)) {
       setError('Priority must be 0..4');
       sel_priority.focus();
       return;
     }
-    /** @type {string} */
     const type = String(sel_type.value || '');
-    /** @type {string} */
     const desc = String(input_description.value || '');
-    /** @type {string[]} */
     const labels = String(input_labels.value || '')
       .split(',')
       .map((s) => s.trim())
@@ -251,10 +249,8 @@ export function createNewIssueDialog(mount_element, sendFn, router, store) {
     } catch {
       list = null;
     }
-    /** @type {string} */
     let created_id = '';
     if (Array.isArray(list)) {
-      /** @type {any[]} */
       const matches = list.filter((it) => String(it.title || '') === title);
       if (matches.length > 0) {
         /** @type {any} */
@@ -326,11 +322,8 @@ export function createNewIssueDialog(mount_element, sendFn, router, store) {
       clearError();
       loadDefaults();
       try {
-        if (
-          'showModal' in dialog &&
-          typeof (/** @type {any} */ (dialog).showModal) === 'function'
-        ) {
-          /** @type {any} */ (dialog).showModal();
+        if ('showModal' in dialog && typeof dialog.showModal === 'function') {
+          dialog.showModal();
         } else {
           dialog.setAttribute('open', '');
         }

package/app/ws.js

@@ -9,7 +9,7 @@
  * Usage:
  *   const ws = createWsClient();
  *   const data = await ws.send('list-issues', { filters: {} });
- *   const off = ws.on('issues-changed', (payload) => { ... });
+ *   const off = ws.on('snapshot', (payload) => { <push event> });
  */
 import { MESSAGE_TYPES, makeRequest, nextId } from './protocol.js';
 
@@ -123,8 +123,6 @@ export function createWsClient(options = {}) {
     state = 'open';
     notifyConnection(state);
     attempts = 0;
-    // subscribe first
-    sendRaw(makeRequest('subscribe-updates', {}));
     // flush queue
     while (queue.length) {
       const req = queue.shift();
@@ -193,16 +191,15 @@ export function createWsClient(options = {}) {
     }
     const url = resolveUrl();
     try {
-      ws = /** @type {any} */ (new WebSocket(url));
+      ws = new WebSocket(url);
       state = 'connecting';
       notifyConnection(state);
-      const s = /** @type {any} */ (ws);
-      s.addEventListener('open', onOpen);
-      s.addEventListener('message', onMessage);
-      s.addEventListener('error', () => {
+      ws.addEventListener('open', onOpen);
+      ws.addEventListener('message', onMessage);
+      ws.addEventListener('error', () => {
         // let close handler handle reconnect
       });
-      s.addEventListener('close', onClose);
+      ws.addEventListener('close', onClose);
     } catch (err) {
       logger.error('ws connect failed', err);
       scheduleReconnect();

package/bin/bdui.js

@@ -10,7 +10,7 @@ const argv = process.argv.slice(2);
 try {
   const code = await main(argv);
   if (Number.isFinite(code)) {
-    process.exitCode = /** @type {number} */ (code);
+    process.exitCode = code;
   }
 } catch (err) {
   console.error(String(/** @type {any} */ (err)?.message || err));

package/docs/adr/001-push-only-lists.md

@@ -0,0 +1,134 @@
+# ADR 001 — Push‑Only Lists (v2)
+
+```
+Date: 2025-10-26
+Status: Accepted (data‑flow details superseded by ADR 002)
+Owner: agent
+```
+
+## Context
+
+The UI currently mixes push updates with read RPCs like `list-issues` and
+`epic-status`. This ADR establishes the push‑only direction for list data and
+removing read RPCs in list views. It predated ADR 002 which later simplified the
+data flow further (per‑subscription stores + full‑issue payloads).
+
+- Push streams provide everything lists need to render. See
+  `docs/protocol/issues-push-v2.md` and ADR 002. Earlier iterations used a
+  central `issues` entity cache plus `list-delta` membership; this has been
+  replaced by per‑subscription stores receiving full issue payloads.
+
+We want every list‑shaped view (Issues, Board, Epics → children) to render
+exclusively from local push data. Reads remain only for mutations that return a
+single updated entity (e.g. detail view refresh).
+
+Related docs:
+
+- Protocol: `docs/protocol/issues-push-v2.md`
+- Server plan: `docs/data-exchange-subscription-plan.md`
+
+## Decision
+
+- One active subscription per visible list. Examples (client ids):
+  - Issues tab: `tab:issues` with spec from filters via `computeIssuesSpec()`
+  - Board: `tab:board:ready|in-progress|closed|blocked`
+  - Epics list: `tab:epics` (for epic entities); children subscribe on expand as
+    `detail:{id}` with `{ type: 'issue-detail', params: { id } }`
+- Rendering reads from two local stores only:
+  - `per‑subscription stores`: one store per active client subscription id.
+    Stores receive versioned `snapshot`/`upsert`/`delete` push envelopes with
+    full issue payloads and expose deterministic, sorted snapshots for the
+    owning view.
+  - `subscriptions`: manages subscription lifecycle and keys. Rendering reads
+    from per‑subscription stores, not from membership ids.
+- Introduce a small selectors utility to apply view‑specific sort rules on store
+  snapshots (no composition from a central cache).
+- Remove read RPCs used for lists: `list-issues`, `epic-status`. Keep mutation
+  RPCs and `show-issue` until detail view also reads from push cache.
+- Tests drive views with push envelopes and `list-delta`; no RPC stubs for
+  reads.
+
+## API Shape (Client)
+
+Subscriptions store (already implemented):
+
+```js
+// app/data/subscriptions-store.js
+createSubscriptionStore(send) -> {
+  wireEvents(on), subscribeList(client_id, spec) -> unsubscribe,
+  selectors: { getIds(client_id), has(client_id), count(client_id) }
+}
+```
+
+Selectors utility (implemented):
+
+```js
+// app/data/list-selectors.js
+/** Compose from per‑subscription store snapshots and apply stable sort. */
+export function createListSelectors(issueStores) {
+  return {
+    selectIssuesFor(client_id) {},
+    selectBoardColumn(client_id, mode) {},
+    selectEpicChildren(epic_id) {},
+    subscribe(fn) {}
+  };
+}
+```
+
+Sorting rules:
+
+- Issues list: priority asc (0..4), then `created_at` desc, then id asc.
+- Board columns: preserve existing view rules (ready → priority asc, then
+  `updated_at` desc; in‑progress → `updated_at` desc; closed → `closed_at`
+  desc).
+- Epics children: same as Issues list unless view specifies otherwise.
+
+## Consequences
+
+Pros:
+
+- Consistent, snappy UI with minimal fetch logic; views are pure derives.
+- Server can batch and coalesce; client renders at most once per envelope.
+- Clear separation: mutations via RPC, reads via push caches.
+
+Cons / Risks:
+
+- Initial implementation work in views and tests.
+- Need disciplined subscription lifecycle on route/tab changes.
+- Requires follow‑up to migrate detail view fully to the push cache.
+
+## Migration Checklist
+
+Views
+
+- [x] Issues view renders from per‑subscription stores; no `list-issues`.
+- [x] Board renders from per‑subscription stores; no `get*` list reads.
+- [x] Epics list/children render from per‑subscription stores; children use
+      `issue-detail` for the epic id; children come from `dependents`.
+
+Client Data Layer
+
+- [x] Add `app/data/list-selectors.js` with helpers listed above (UI-156).
+- [x] Remove list read functions from `app/data/providers.js` (UI-159).
+- [ ] Keep `getIssue` and all mutation helpers until detail view push migration
+      happens (follow‑up).
+
+Tests
+
+- [x] Update list/board/epics tests to use per‑subscription push envelopes
+      (UI-158).
+- [x] Remove RPC read stubs from tests.
+
+Docs
+
+- [x] This ADR committed (UI-152).
+- [x] Update protocol and architecture docs for push‑only model (UI-160).
+
+## Notes
+
+- Client ids used in this repo today:
+  - `tab:issues` for the Issues view
+  - `tab:board:ready|in-progress|closed|blocked` for Board columns
+  - `tab:epics` for the Epics tab; `epic:${id}` for expanded children
+- See `app/main.js` for current subscription wiring, filter → spec mapping, and
+  per‑subscription push routing.