From 495d042a98022676e2668bea3ac03a3f10bef0ad Mon Sep 17 00:00:00 2001 From: ducoterra Date: Sun, 6 Sep 2026 22:54:58 -0400 Subject: [PATCH] =?UTF-8?q?chore(agent):=20phase=20roadmap=20from=20TODO.m?= =?UTF-8?q?d=20=E2=80=94=204=20phases=20(77=E2=80=9380)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Protocol B append: navbar refresh + History refresh button (77, TODO L3), static background — glow layers removed (78, TODO L4), admin-issued API tokens with the in-app gate + browser caching, only shared chats stay anonymous (79, TODO L5), onboarding chips as the last 3 questions asked with the env seed only before the first (80, TODO L6). TODO.md cleared — its items now live in .agents/phases/todo/. Owner-confirmed assumptions recorded in each phase overview (A1–A7, chat 2026-09-06). --- .../phases/todo/77_navbar_refresh/00_phase.md | 41 ++++++++++++++ .../01_router_refresh_hook.md | 24 +++++++++ .../02_refresh_other_views.md | 23 ++++++++ .../03_history_refresh_button.md | 29 ++++++++++ .../todo/78_static_background/00_phase.md | 42 +++++++++++++++ .../01_remove_glow_layers.md | 25 +++++++++ .../02_regression_sweep_commit.md | 20 +++++++ .agents/phases/todo/79_api_tokens/00_phase.md | 53 +++++++++++++++++++ .../79_api_tokens/01_token_model_migration.md | 21 ++++++++ .../todo/79_api_tokens/02_token_admin_api.md | 27 ++++++++++ .../03_token_auth_enforcement.md | 27 ++++++++++ .../79_api_tokens/04_migrate_anonymous_e2e.md | 22 ++++++++ .../79_api_tokens/05_frontend_token_gate.md | 34 ++++++++++++ .../79_api_tokens/06_tokens_admin_view.md | 32 +++++++++++ .../todo/79_api_tokens/07_e2e_story_suite.md | 28 ++++++++++ .../08_regression_sweep_commit.md | 23 ++++++++ .../80_history_suggestion_chips/00_phase.md | 40 ++++++++++++++ .../01_last_questions_endpoint.md | 37 +++++++++++++ .../02_seed_semantics_docs.md | 20 +++++++ .../03_chips_new_chat_refetch.md | 21 ++++++++ .../04_e2e_suite_commit.md | 27 ++++++++++ 21 files changed, 616 insertions(+) create mode 100644 .agents/phases/todo/77_navbar_refresh/00_phase.md create mode 100644 .agents/phases/todo/77_navbar_refresh/01_router_refresh_hook.md create mode 100644 .agents/phases/todo/77_navbar_refresh/02_refresh_other_views.md create mode 100644 .agents/phases/todo/77_navbar_refresh/03_history_refresh_button.md create mode 100644 .agents/phases/todo/78_static_background/00_phase.md create mode 100644 .agents/phases/todo/78_static_background/01_remove_glow_layers.md create mode 100644 .agents/phases/todo/78_static_background/02_regression_sweep_commit.md create mode 100644 .agents/phases/todo/79_api_tokens/00_phase.md create mode 100644 .agents/phases/todo/79_api_tokens/01_token_model_migration.md create mode 100644 .agents/phases/todo/79_api_tokens/02_token_admin_api.md create mode 100644 .agents/phases/todo/79_api_tokens/03_token_auth_enforcement.md create mode 100644 .agents/phases/todo/79_api_tokens/04_migrate_anonymous_e2e.md create mode 100644 .agents/phases/todo/79_api_tokens/05_frontend_token_gate.md create mode 100644 .agents/phases/todo/79_api_tokens/06_tokens_admin_view.md create mode 100644 .agents/phases/todo/79_api_tokens/07_e2e_story_suite.md create mode 100644 .agents/phases/todo/79_api_tokens/08_regression_sweep_commit.md create mode 100644 .agents/phases/todo/80_history_suggestion_chips/00_phase.md create mode 100644 .agents/phases/todo/80_history_suggestion_chips/01_last_questions_endpoint.md create mode 100644 .agents/phases/todo/80_history_suggestion_chips/02_seed_semantics_docs.md create mode 100644 .agents/phases/todo/80_history_suggestion_chips/03_chips_new_chat_refetch.md create mode 100644 .agents/phases/todo/80_history_suggestion_chips/04_e2e_suite_commit.md diff --git a/.agents/phases/todo/77_navbar_refresh/00_phase.md b/.agents/phases/todo/77_navbar_refresh/00_phase.md new file mode 100644 index 0000000..bb61307 --- /dev/null +++ b/.agents/phases/todo/77_navbar_refresh/00_phase.md @@ -0,0 +1,41 @@ +# Phase 77 — Navbar clicks refresh the view's data (fresh list on re-show + a History refresh button) + +**Source:** `TODO.md` L3 — "Clicking navbar icons should refresh the relevant page. For example, clicking 'history' doesn't load new history until I refresh. The history page should also have a refresh button." +**Story:** n/a (TODO-derived — descendant of `.agents/user_stories/chat-history.md` (phase 50) and the phase-76 shell) +**Context:** `frontend/assets/router.js` (the phase-76 shell router: the `VIEW` map, mount-once / hide-forever, `switchTo(name, { userInitiated })`, the delegated nav click handler with its `name === current` early return, the `popstate` handler), `frontend/assets/history.js` (the History view module — `loadChats()` APPENDS rows and is called once at mount), `frontend/assets/sources.js` (`loadDocs()` ~line 472 — already clears `tbody` before rendering), `frontend/assets/git-sources.js` (`loadSources()` ~line 230 — render + announce), `frontend/assets/tuning.js` (`loadNotes()` ~line 116 — `renderNotes` clears), `frontend/index.html` (`#view-history`'s `.page-head` — h1 "Saved chats" + sub; the `#history-status` live region), `tests/unit/test_frontend_router.py` (the source-level router pins), `tests/e2e/test_nav_switch_keeps_stream.py` (the phase-76 suite — must stay green UNCHANGED). + +## Objective +Since the phase-76 shell, a view's data is fetched exactly once, at mount (mount-once, hide-forever) — a History view opened at 10:00 still shows 10:00's data at 10:30. Make every user-initiated re-show of a view re-fetch its list, and give History an explicit Refresh button. The Chat view is deliberately out of scope: its in-flight stream and local conversation must survive (the phase-76 contract). + +## Owner decisions (chat, 2026-09-06 — recorded per AGENTS.md rule 3) +- **A1 confirmed:** "the relevant page" = the four data views (History, RAG, Sources, Tuning). **Chat is EXCLUDED from the refresh hook** — the in-flight SSE stream and the local conversation persist (the phase-76 LOCKED refinement). +- The refresh fires on: (a) a switch TO the view when it is already mounted, (b) a re-click of the active view's own nav link (today a no-op), (c) back/forward (`popstate`) onto an already-mounted view. The FIRST show (the mount) and the boot never fire it — the mount's own load is the first fetch. +- The History refresh button lives in the view's page-head and announces through the existing `#history-status` live region. + +## Design (shared by all tasks — the executor reads this, not the chat) +- **Mechanism — a DOM event, zero router-state changes:** on any user-initiated re-show, the router dispatches `new CustomEvent("bor:view-refresh")` on the view's `
` root. A view module that wants fresh data listens on its own `root` inside `mount()` and re-runs its existing load function. Modules that do not listen are unaffected — the chat view never listens. +- **First-show exemption (the no-double-fetch rule):** in `switchTo`, capture `const wasMounted = mounted[name]` BEFORE the mount block. After the view is shown and the head/nav state is written, dispatch the event `if (wasMounted)` — a re-show. The first show (mount) loads once and dispatches nothing; boot (`userInitiated: false`) can never dispatch (boot always finds an unmounted view or the chat view, and the dispatch site is gated on `wasMounted`). +- **Active-view re-click:** the click handler's `if (name === current) return;` becomes: dispatch `bor:view-refresh` on `viewEls[name]` and return — NO `pushState` (the URL already IS that view's path); the mobile menu still closes (the container handler runs regardless). +- **Re-entrance of the load functions:** each must be safe to call repeatedly. Verified: `sources.js` `loadDocs` clears via `tbody.replaceChildren()` (check its `showEmpty()` path also clears the rows — if not, clear at the top of `loadDocs`); `tuning.js` `renderNotes` clears via `tuneList.textContent = ""`; `git-sources.js` `renderSources` replaces the list (verify the error/empty states reset on a re-call — `showLoadError` hides table AND empty state). `history.js` `loadChats` **APPENDS** — it must remove the data rows (every `tr` in `#history-tbody` EXCEPT the hidden `#history-empty-row`) before re-fetching. +- **Gate guard:** a view only re-fetches after its whoami gate has passed (History: anonymous shows `#history-gate` and NEVER calls `/api/chats` — the phase-50 contract the story E2E pins; the listener must respect the same branch). +- **Focus/scroll unchanged:** the router still lands the viewport at the top on user-initiated switches; the refresh is a background re-fetch behind the already-shown view. +- **E2E "freshness" proof:** create new backing data via the API AFTER a view has loaded, nav back (or re-click / refresh-button), assert the new row — with the phase-76 canonical same-document sentinel (`window` global set before the clicks is still readable after — no document load). + +## Dependencies +— (none; builds on the completed phase-76 shell) + +## Tasks +1. `01_router_refresh_hook.md` — the `bor:view-refresh` dispatch in `router.js` (re-show + active re-click + popstate; first show exempt) and the History view re-fetching on it. +2. `02_refresh_other_views.md` — RAG, Sources, and Tuning listen and re-fetch; the Chat view stays untouched (with a comment pinning the exclusion). +3. `03_history_refresh_button.md` — the History Refresh button + the story E2E suite `test_navbar_refresh.py` + the regression sweep + the atomic commit. + +## Testing & Quality +- Unit: `tests/unit/test_frontend_router.py` — new source-level pins: the `bor:view-refresh` literal exists; the dispatch is gated on the pre-mount `mounted` state (first show exempt); the re-click branch dispatches instead of a bare `return` (no `pushState`); the three other view modules each carry a listener and `app.js` does NOT (negative pin). +- E2E: new story suite `tests/e2e/test_navbar_refresh.py` run in isolation (the scenarios live in task 03). +- Coverage: **>90%** on `app/` — this phase is frontend-only; the floor is preserved by not regressing. + +## Completion Criteria +- [ ] `uv run pytest tests/e2e/test_navbar_refresh.py -v --no-cov` green in isolation (DB up). +- [ ] `tests/e2e/test_nav_switch_keeps_stream.py` still green UNCHANGED (the stream-survival contract holds with the hook in place). +- [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` >90%; `uv run ruff check . && uv run pyright` clean. +- [ ] One atomic `--no-gpg-sign` Conventional-Commits commit (e.g. `feat(ui): refresh view data on navbar re-show + History refresh button`) whose body cites TODO.md L3; phase dir moved to `.agents/phases/complete/`. diff --git a/.agents/phases/todo/77_navbar_refresh/01_router_refresh_hook.md b/.agents/phases/todo/77_navbar_refresh/01_router_refresh_hook.md new file mode 100644 index 0000000..6ab5bdd --- /dev/null +++ b/.agents/phases/todo/77_navbar_refresh/01_router_refresh_hook.md @@ -0,0 +1,24 @@ +# Task 01 — The `bor:view-refresh` hook; History re-fetches on a user-initiated re-show + +**Phase:** `77_navbar_refresh` · **Source:** `TODO.md:3` — "Clicking navbar icons should refresh the relevant page. For example, clicking 'history' doesn't load new history until I refresh." +**Story:** n/a (TODO-derived) + +## Objective +A user-initiated re-show of an already-mounted view re-fetches its data: `router.js` dispatches `bor:view-refresh` on the view's section (re-shows and active re-clicks only — never on the first mount or boot), and the History view listens and re-loads its chat list. + +## Work +1. `frontend/assets/router.js` — in `switchTo`: capture `const wasMounted = mounted[name]` BEFORE the mount block; after the show + head/nav state is written (before the focus/scroll tail is fine — the event order is: visible → refresh dispatched), `if (wasMounted) root.dispatchEvent(new CustomEvent("bor:view-refresh"))`. In the delegated nav click handler, replace the `if (name === current) return;` early return with a dispatch of `bor:view-refresh` on `viewEls[name]` + `return` (no `pushState` — the URL is already this view's path; the mobile menu still closes via the container handler). The `popstate` path flows through `switchTo`, so it inherits the `wasMounted` gating automatically. Update the file-header contract comment with the refresh rule: the event fires exactly when an already-mounted view is shown again — first show and boot never (the mount's own load is the first fetch). +2. `frontend/assets/history.js` — inside `mount(root)`: + - make `loadChats()` re-entrant: at its top, remove the data rows — every `tr` in `#history-tbody` EXCEPT the hidden `#history-empty-row` — so a re-load replaces the list instead of appending a duplicate set; + - add the listener in the ADMIN branch (after the `fetchIsAdmin()` gate passes — anonymous shows `#history-gate` and never fetches, per the phase-50 contract the story E2E pins): `root.addEventListener("bor:view-refresh", () => { if (started) loadChats(); })` where `started` flips to `true` once the first `loadChats()` call is made (the gate branch that `return`s early must not arm a listener that fetches). +3. `tests/unit/test_frontend_router.py` — new source pins (house pattern — read the JS source, no browser): the `bor:view-refresh` literal exists in `router.js`; the dispatch site is guarded by a pre-mount `mounted` capture (assert the `wasMounted`-style capture appears before the mount block — e.g. the capture assignment precedes the `mounted[name]` set); the re-click branch dispatches (assert the `name === current` branch contains the dispatch literal, not a bare return); `history.js` contains the listener. + +## Testing & Quality +- Unit: item 3 (mechanism-level pins; the existing router pins — pushState switches, mount-once, hidden+inert, single-writer head/nav — must stay green UNCHANGED). +- E2E: none yet — the story suite lands in task 03. +- Coverage: n/a for this task (frontend-only) — the `app/` floor must not regress. + +## Completion Criteria +- [ ] `uv run pytest tests/unit/test_frontend_router.py -v` green (old + new pins). +- [ ] Manual spot check (optional): load History as admin, save a new chat via the API, click another view then History again — the new row is there without a document reload. +- [ ] `uv run ruff check . && uv run pyright` clean — the gate runs after this task. diff --git a/.agents/phases/todo/77_navbar_refresh/02_refresh_other_views.md b/.agents/phases/todo/77_navbar_refresh/02_refresh_other_views.md new file mode 100644 index 0000000..d1ea9f8 --- /dev/null +++ b/.agents/phases/todo/77_navbar_refresh/02_refresh_other_views.md @@ -0,0 +1,23 @@ +# Task 02 — RAG, Sources, and Tuning join the refresh (Chat stays out) + +**Phase:** `77_navbar_refresh` · **Source:** `TODO.md:3` — "Clicking navbar icons should refresh the relevant page." +**Story:** n/a (TODO-derived) + +## Objective +The three remaining data views re-fetch on `bor:view-refresh` with the same gate-guarded, re-entrant pattern as History. The Chat view deliberately does NOT listen — its in-flight stream and local conversation persist (the phase-76 contract). + +## Work +1. `frontend/assets/sources.js` — in `mount(root)`, in the admin branch (after the `fetchIsAdmin()` gate passes): `root.addEventListener("bor:view-refresh", () => loadDocs())`. Verify `loadDocs()` re-entrance end to end: the populated path already clears (`tbody.replaceChildren()`); check the `showEmpty()` path — if it does not clear the tbody rows, a refresh from a populated list into an empty result would leave ghost rows: add the row-clear at the top of `loadDocs()` (the hidden empty-row stays in place, exactly the History pattern from task 01). +2. `frontend/assets/git-sources.js` — same: `root.addEventListener("bor:view-refresh", () => loadSources())` in the admin branch. Verify a re-call resets all three list states (populated render, the empty state, and the `showLoadError` state — `showLoadError` already hides the table AND the empty state, so an error followed by a successful refresh must clear the error: `loadSources` already calls `hideLoadError()` on success — confirm). +3. `frontend/assets/tuning.js` — same: `root.addEventListener("bor:view-refresh", () => loadNotes())` in the admin branch; `renderNotes` already clears (`tuneList.textContent = ""`). Note: `loadNotes` keeps the last rendered list on a failed fetch (its documented contract) — a refresh that fails must behave the same way (no change needed; the listener just calls the function). +4. `frontend/assets/app.js` (the chat view) — add NO listener. Add a one-line comment where the chat view's module-scope state begins: the `bor:view-refresh` exclusion is deliberate — the in-flight SSE stream and the local conversation must survive every switch (phase 76), so the chat view never re-fetches on a show. +5. `tests/unit/test_frontend_router.py` (or the neighboring source-pin file if the house split the pins — match where the task-01 pins landed) — source pins: `sources.js`, `git-sources.js`, and `tuning.js` each contain the `bor:view-refresh` listener; `app.js` does NOT (negative pin — the exclusion is a contract, not an oversight). + +## Testing & Quality +- Unit: item 5. +- E2E: covered by the task-03 story suite — one assertion per view (mutate the backing data via the API while the view is hidden, nav back, the row reflects the mutation; where a view's backing data has no cheap API mutation path, assert via the Playwright request log that the re-fetch happened on re-show). +- Coverage: n/a (frontend) — the `app/` floor preserved. + +## Completion Criteria +- [ ] All four data views re-fetch on a re-show; the chat view is untouched (stream survival still holds — `test_nav_switch_keeps_stream.py` green). +- [ ] The new unit pins are green; `uv run ruff check . && uv run pyright` clean — the gate runs after this task. diff --git a/.agents/phases/todo/77_navbar_refresh/03_history_refresh_button.md b/.agents/phases/todo/77_navbar_refresh/03_history_refresh_button.md new file mode 100644 index 0000000..bc7e706 --- /dev/null +++ b/.agents/phases/todo/77_navbar_refresh/03_history_refresh_button.md @@ -0,0 +1,29 @@ +# Task 03 — History refresh button + the story E2E suite + the commit + +**Phase:** `77_navbar_refresh` · **Source:** `TODO.md:3` — "…The history page should also have a refresh button." +**Story:** n/a (TODO-derived) + +## Objective +The explicit half of the item: a visible Refresh control on the History view — plus the phase's Playwright story suite proving every refresh path, the regression sweep, and the atomic commit. + +## Work +1. `frontend/index.html` — in `#view-history`'s `.page-head`: add a right-aligned actions slot (`.page-head` becomes a flex row — title block left, actions right; wraps below 640px): ``, a `#token-once` block (`hidden`): the "shown once" copy line, a mono read-only field `` + ``, and the full-width table (AGENTS.md rule 5 — no skinny list): `#tokens-table` with thead Label | Created | Last used | Status | Actions (the Actions header visually-hidden, the row buttons carry aria-labels — the history-table convention), `#tokens-tbody` + a hidden `#tokens-empty-row`. +2. `frontend/assets/tokens.js` (new — `export async function mount(root)`, the `history.js` structure as the template, ALL cells via textContent — labels are admin-derived, still textContent, the XSS-safe-by-construction house rule): + - admin gate: `if (!(await fetchIsAdmin()))` → show `#tokens-gate`, hide the table, NO fetch (the router 403s anonymous — the same request-log contract as the history view); + - `loadTokens()` → `GET /api/tokens` → rows: label; created (locale date+time, full ISO in `title`); last used (locale or "never"); Status — an "Active" em-dash vs a rose "Revoked" pill (the stale-pill visual language, `aria-label` on the cell in BOTH states — WCAG); Actions — Revoke (the inline two-step, the `history-confirm-*` pattern: first click swaps to "Revoke? [Yes] [No]", focus to Yes, Yes → `POST /api/tokens//revoke` → row re-renders Revoked + announce; No / failure restores) — Revoked rows show NO action (nothing left to revoke); + - generate: label from `#token-label` (blank → send `"token"` — the placeholder documents the fallback; the API's 1–120 validator is satisfied) → `POST /api/tokens` → 201 → `#token-once` visible with the plaintext in `#token-once-value` + [Copy] (clipboard + the inline-fallback house pattern — `tokens.js` keeps its OWN ~10-line copy, the per-page duplication house style) + announce "Token created — copy it now; it won't be shown again." → `loadTokens()` (the new row appears Active) → the once-block HIDES on the next `loadTokens()` / re-show (the plaintext is NOT stored anywhere client-side — no localStorage, no data attribute); + - the re-fetch contract from phase 77: `root.addEventListener("bor:view-refresh", () => { if (loaded) loadTokens(); })` — a re-show re-lists (and re-hides the once-block, if one was up); + - every action lands a line in `#tokens-status` (success or failure — the never-stale feedback contract). +3. `frontend/assets/router.js` — the phase-76 fold entries: `VIEW["/tokens.html"] = "tokens"`; `VIEW_PATH.tokens = "/tokens.html"`; `VIEW_MODULES.tokens = () => import("./tokens.js")`; `TITLES.tokens = "Access tokens · Brain of Reese"`; `DESCRIPTIONS.tokens = "Generate and revoke the API tokens that let people use the app."` (the `replaceAll` brand-composition contract applies — no hardcoded-name write). +4. `frontend/assets/header.js` — reveal `#nav-tokens` for role admin in `initSharedHeader()` (the SAME ship-hidden / reveal-for-admin contract as the other four links — one more line, same pattern). +5. `app/main.py` — `"/tokens.html"` into the `_shell_routes` tuple (the list is caller-driven — the phase-76 comment documents exactly this extension); `app/core/caching.py` — `"/tokens.html"` into `HTML_PAGES` (the no-cache + `?v=` contract for the deep link). Then the phase-76 task-03 test updates: run `uv run pytest tests/integration` and extend whatever asserts the shell-route / title-table / `_page_file`-override map (the phase-76 task 03 work items named these — follow the same shape for the sixth path). +6. `frontend/assets/styles.css` — the create row (flex, wraps ≤640px), the once-block (mono field, the copy button — the `share-link-fallback` visual language), the table (the `history-table` visual language — full-width, the AGENTS.md rule-5 shape), the Active/Revoked pills (the `stale-pill` rose for Revoked, a plain em-dash for Active), `focus-visible` + 4.5:1 throughout. +7. `tests/unit/test_frontend_router.py` — the view-map pins adapt to the sixth entry (mechanism-level pins should hold as-is — verify; if a pin enumerates the views, extend the enumeration). + +## Testing & Quality +- Unit: item 7 + the source-pin convention for view modules (if the house pins the other four modules' `export async function mount`, `tokens.js` gets the same pin). +- Integration: the `/tokens.html` shell-route + caching assertions (item 5). +- E2E: covered by the task-07 story suite (admin UI: generate → once-field + copy, list, revoke two-step). +- Coverage: **>90%** on the modified `app/` code (`main.py` tuple + `caching.py` list — one line each, exercised by the integration assertions). + +## Completion Criteria +- [ ] The admin sees the Tokens nav link (desktop + mobile menu); anonymous and token users never do (ship-hidden + role check — even mid-DOM, the link is `hidden`). +- [ ] Direct load of `/tokens.html` deep-links to the view (admin: the table; anonymous: the gate) and carries the no-cache + `?v=` contract (the cache-busting suites green with the new page). +- [ ] Generate → plaintext once + copy works (clipboard + the http fallback); revoke → two-step → Revoked; the cache-busting + nav-switch suites stay green. diff --git a/.agents/phases/todo/79_api_tokens/07_e2e_story_suite.md b/.agents/phases/todo/79_api_tokens/07_e2e_story_suite.md new file mode 100644 index 0000000..8218c33 --- /dev/null +++ b/.agents/phases/todo/79_api_tokens/07_e2e_story_suite.md @@ -0,0 +1,28 @@ +# Task 07 — The story E2E suite: `tests/e2e/test_api_tokens.py` + +**Phase:** `79_api_tokens` · **Source:** `TODO.md:5` — "Add api tokens that the admin can generate and hand out so people can log in to use the app. The only thing that should be accessible without an API token is shared chats. The web ui should ask for a token before letting a user through and should cache that token in browser storage so they don't have to keep entering it." +**Story:** n/a (TODO-derived) + +## Objective +The owner's sentence, pinned in a real browser: the admin generates a token and hands it out (a fresh context); the holder uses the app; the ONLY anonymous content is shared chats; the cached token removes the re-entry; revocation closes the door. + +## Work +1. `tests/e2e/test_api_tokens.py` (NEW — run in isolation: `uv run pytest tests/e2e/test_api_tokens.py -v --no-cov`; DB up, the mock-LLM fixture; fresh browser contexts per scenario — no cached token leaks between tests): + - **anonymous is locked out:** fresh context → chat page: `#auth-gate` visible; the composer (`#message-input`) is NOT keyboard-reachable (the `#main` inert lock — the Tab-order assertion pattern from `test_suggestion_chips.py`'s keyboard walk, inverted); direct API with the context's (empty) cookies: `POST /api/chat` → 401, `GET /api/suggestions` → 401, `GET /api/documents/content?source=…&path=…` → 401. + - **shared stays open:** as admin, create + share a saved chat (`POST /api/chats` + `POST /api/chats//share` — the house API pattern from `test_share_chat.py`) → a FRESH context opens `/shared/` anonymously → the conversation renders (no gate anywhere on that page). + - **admin generates (UI):** signed-in admin (`auth_helpers.login`) → nav to Tokens → label "e2e-alice" → Generate → `#token-once-value` carries `^bor_[0-9a-f]{32}$` (read it into the test) → the table shows an Active row "e2e-alice"; the once-block hides on a re-show (nav away + back → `#token-once` hidden — the plaintext is gone). + - **the token flow (fresh context):** `login_with_token(page, app_url, token)` (the task-04 helper) → gate hidden → ask a question (mock LLM) → the brain bubble renders → a cited source chip opens the document (the same-page modal) → the admin nav links (RAG, Sources, Tuning, History, Tokens) are ALL absent from `#app-nav` (the role-`user` contract) and Sign out is visible. + - **caching:** `page.reload()` → NO gate (`#auth-gate` hidden) — the silent re-auth from localStorage; the chat UI is interactive without re-entry. + - **admin-only walls (the token user's cookies, httpx):** `GET /api/tokens` 403, `GET /api/chats` 403, `GET /api/docs` 403, `POST /api/steering` 403, `GET /api/git-sources` 403. + - **sign out:** the token user clicks Sign out → back to the gate; `localStorage.getItem("bor.token")` is `null` (Playwright `page.evaluate`). + - **revocation:** admin revokes the token (UI two-step: Revoke → Yes) → the token user's NEXT action 401s (ask a question → the error banner, or assert `POST /api/chat` 401 with the context cookies) and a FRESH `login_with_token` attempt with the same token fails (`#auth-gate-error` visible, gate stays). + - **wrong token:** fresh context, `login_with_token(…, token="bor_" + "0" * 32)` → `#auth-gate-error` visible, still anonymous (the API also 401s — the generic message, no enumeration: the error body for a wrong-format token equals the one for a well-formed unknown token). +2. Run in isolation until green; fix app bugs the suite exposes (the suite is the spec — the owner's sentence). + +## Testing & Quality +- This file IS the story gate (AGENTS.md rules 4 + 9 — one file per story, run in isolation). +- Coverage: n/a (E2E) — the `app/` floor preserved. + +## Completion Criteria +- [ ] `uv run pytest tests/e2e/test_api_tokens.py -v --no-cov` green in isolation. +- [ ] Every clause of TODO.md L5 is asserted: generate (UI), hand out (fresh context), use the app (chat + document), only-shared-chats-open (the anonymous matrix), cached token (reload without re-entry), revocation (immediate refusal). diff --git a/.agents/phases/todo/79_api_tokens/08_regression_sweep_commit.md b/.agents/phases/todo/79_api_tokens/08_regression_sweep_commit.md new file mode 100644 index 0000000..b85ec48 --- /dev/null +++ b/.agents/phases/todo/79_api_tokens/08_regression_sweep_commit.md @@ -0,0 +1,23 @@ +# Task 08 — Regression sweep + the commit + +**Phase:** `79_api_tokens` · **Source:** `TODO.md:5` +**Story:** n/a (TODO-derived) + +## Objective +The full pipeline green against the gated app, the operator docs updated, one atomic commit, the phase closed. + +## Work +1. Full unit + integration: `uv run pytest --cov=app --cov-report=term-missing` — **>90%** on `app/` (the delta: `app/core/tokens.py`, `app/api/tokens.py`, and the modified `app/core/auth.py` / `app/api/auth.py` / `app/api/chat.py` / `app/api/suggestions.py` / `app/api/docs.py` — every new branch tested per tasks 02/03). +2. `uv run ruff check . && uv run pyright`. +3. E2E inventory spot-checks in isolation (the high-touch files): `test_api_tokens.py`, `test_admin_auth.py`, `test_share_chat.py` (ANONYMOUS), `test_chat_rag.py` (migrated), `test_nav_switch_keeps_stream.py` (the phase-76 contract under the gate), `test_smoke.py`. +4. Manual verification in a real browser (real LLM, real server): the admin generates a token; a private window enters it at the gate, chats, opens a cited document, reloads WITHOUT re-entry; an anonymous window meets the gate and opens a shared chat; the admin revokes the token and the private window's next question fails. +5. Operator docs: `README.md` — the "Admin & sign-in" section gains a short "API tokens" subsection (how to generate one in the Tokens view, what a token user can and cannot do, the gate + the browser cache, revocation semantics — immediate on the next request). `.env.example` — UNCHANGED (no new environment variable: tokens live in the DB, generated by the admin — verify no settings were added; if any task added one, the doc goes here). +6. ONE atomic `--no-gpg-sign` Conventional-Commits commit — e.g. `feat(auth): admin-issued API tokens gate the app; only shared chats stay anonymous` — body cites TODO.md L5 + the confirmed scope decision (A3–A5: token users get chat/suggestions/document viewer; every admin surface untouched). Move the phase dir to `.agents/phases/complete/`. + +## Testing & Quality +- The full suite IS the test; coverage **>90%** on `app/`. + +## Completion Criteria +- [ ] Items 1–4 all green/verified. +- [ ] README documents the token flow for the operator. +- [ ] Committed; phase dir in `.agents/phases/complete/`. diff --git a/.agents/phases/todo/80_history_suggestion_chips/00_phase.md b/.agents/phases/todo/80_history_suggestion_chips/00_phase.md new file mode 100644 index 0000000..2af9df1 --- /dev/null +++ b/.agents/phases/todo/80_history_suggestion_chips/00_phase.md @@ -0,0 +1,40 @@ +# Phase 80 — Onboarding chips: the last 3 questions asked (the env var seeds a fresh deployment) + +**Source:** `TODO.md` L6 — "The chat suggestions (suggestion chips) should be the last 3 questions asked rather than supplied by env vars. The env var should be used to offer questions before any have been asked as a 'seed' for a new deployment." +**Story:** n/a (TODO-derived — extends `.agents/user_stories/suggestion-chips.md` (phase 05)) +**Context:** `app/api/suggestions.py` (`GET /api/suggestions` → `settings.suggestions` — a static list, 15 lines today), `app/config.py` (`suggestions: list[str]` — the 4 built-in defaults + the `BOR_SUGGESTIONS` env override; `.env.example:55`; `README.md:782` env-table row), `app/models.py` (`SavedChat.messages` — the JSONB `bor.chat.v1` record: a list of `{who, text, sources?, …}` entries, conversational order oldest→newest; `updated_at` stamped on save), `app/rag/suggestions.py` (the deflection "Maybe try" chips — `derive_suggestions`, a SEPARATE contract, untouched by this phase), `frontend/assets/app.js` (`loadSuggestions()` at boot → `renderChips` into `#suggestions` (role="list") inside `#empty-state` (~line 159 of `index.html`); `startNewChat()` — the empty state comes back with STALE chips), `tests/e2e/test_suggestion_chips.py` (the phase-05 suite — pins the settings-defaults contract; REWRITTEN in task 04 per the phase-76 precedent), `tests/integration/test_api.py` (current `/api/suggestions` integration pins). + +## Objective +The onboarding chips reflect the deployment's recent activity: the 3 most recent questions actually asked (across saved chats), newest first. A brand-new deployment — zero saved questions — gets the seed list instead (`BOR_SUGGESTIONS`, or the built-in default while unset). The chips also refresh when the empty state comes back (New chat), so the row is never stale. The LLM "Maybe try" deflection chips are untouched. + +## Owner decisions (chat, 2026-09-06 — recorded per AGENTS.md rule 3) +- **A6 confirmed:** "the last 3 questions asked" = the 3 most recent USER questions across ALL `saved_chats` — chats walked newest-`updated_at` first, each chat's `messages` walked newest-first, collecting entries with `who == "user"` and a non-blank `text` — de-duplicated (exact, case-sensitive match; a verbatim re-ask counts once), cap 3 applied AFTER dedup. 1–2 saved questions → exactly those show (NO mixing with the seed). ZERO saved questions → the full seed list. +- **A7 confirmed:** only the onboarding row (`#suggestions` in the empty state) changes. The deflection "Maybe try" chips (title-derived via `app.rag/suggestions.derive_suggestions`, carried in the chat response) keep their contract. +- **Scope is deployment-wide:** saved chats have no per-user attribution and are created only by the admin (phase 79 keeps the save surface admin-only) — the chips reflect the admin's recent questions; there is no per-user question history to scope by (and no new attribution is added in this phase). + +## Design (shared by all tasks) +- **Extraction — `app/api/suggestions.py`:** the endpoint gains the `db` dependency and a module-level `last_questions(db, limit: int = 3) -> list[str]`: `SELECT … FROM saved_chats ORDER BY updated_at DESC, created_at DESC` (the tiebreak keeps the order deterministic when timestamps collide); for each chat, walk `chat.messages` (the JSONB column deserializes to a Python list of dicts — NO SQL JSON ops needed; the message counts are the `bor.chat.v1` conversation sizes) in REVERSE (newest first), collecting `m["text"].strip()` for entries where `m.get("who") == "user"`, skipping blanks, stopping once `limit` UNIQUE texts are collected (exact case-sensitive dedup — the docstring notes the choice: case-insensitive dedup would drop a legitimate differently-cased re-ask). Result order = encounter order (newest first). +- **The endpoint:** `qs = last_questions(db)` → `SuggestionList(suggestions=qs if qs else get_settings().suggestions)` — the seed (`BOR_SUGGESTIONS` override or the built-in default) appears ONLY when the walk yields zero questions. The endpoint is `require_user`-gated by phase 79 (admin OR token user) — no auth change here; the tests sign in first. +- **The deflection path is untouched:** `app/rag/suggestions.py` (`derive_suggestions` — used by the chat turn for the "Maybe try" row) does not call this endpoint and is not modified; its tests stay green. +- **Frontend — the refetch (task 03):** `startNewChat()` (the `bor:new-chat` handler in `app.js`) gains a `loadSuggestions()` call when it restores the empty state — the existing function (fetch `/api/suggestions` → `renderChips` into `#suggestions`, replacing the previous chips in place; progressive enhancement, swallows its own failures). The boot fetch stays. No other frontend change: the chips' one-tap submit, the role="list" semantics, and the "Maybe try" row are all existing contracts. +- **Docs (task 02):** `BOR_SUGGESTIONS` is documented as the SEED — shown only before any question has ever been saved — in the `config.py` docstring, `.env.example:55`, and the README (the env-table row + the chat feature description). + +## Dependencies +- `79_api_tokens` (todo) — `/api/suggestions` is `require_user`-gated there; this phase's tests sign in first and build on that contract (a token user ALSO sees the deployment-wide chips — consistent with A6's deployment-wide scope). + +## Tasks +1. `01_last_questions_endpoint.md` — the `last_questions` extraction + the seed fallback + the integration state matrix. +2. `02_seed_semantics_docs.md` — the config / `.env.example` / README doc updates. +3. `03_chips_new_chat_refetch.md` — the app.js refetch on New chat + the source pin. +4. `04_e2e_suite_commit.md` — the story-suite rewrite to the new semantics + the full gate + the atomic commit. + +## Testing & Quality +- Integration: the full state matrix for `/api/suggestions` (empty DB → the built-in seed; `BOR_SUGGESTIONS` override → the override while empty; 4 questions in one chat → the 3 newest; two chats → the `updated_at` order respected; dedup; exactly 2 questions → 2 chips, no top-up; brain-only messages never picked). +- E2E: the REWRITTEN `tests/e2e/test_suggestion_chips.py` run in isolation (the phase-76 precedent — a semantic change rewrites the story suite in place). +- Coverage: **>90%** on `app/` (the delta is the ~30-line helper + endpoint in `app/api/suggestions.py` — every branch covered). + +## Completion Criteria +- [ ] `uv run pytest tests/e2e/test_suggestion_chips.py -v --no-cov` green in isolation. +- [ ] The deflection chips are UNCHANGED (`derive_suggestions` + its suites green). +- [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` >90%; `uv run ruff check . && uv run pyright` clean. +- [ ] One atomic `--no-gpg-sign` Conventional-Commits commit (e.g. `feat(chat): onboarding chips are the last 3 questions asked; the env seed only before the first`); phase dir moved to `.agents/phases/complete/`. diff --git a/.agents/phases/todo/80_history_suggestion_chips/01_last_questions_endpoint.md b/.agents/phases/todo/80_history_suggestion_chips/01_last_questions_endpoint.md new file mode 100644 index 0000000..b9765e9 --- /dev/null +++ b/.agents/phases/todo/80_history_suggestion_chips/01_last_questions_endpoint.md @@ -0,0 +1,37 @@ +# Task 01 — `/api/suggestions` returns the last 3 questions asked (the seed before the first) + +**Phase:** `80_history_suggestion_chips` · **Source:** `TODO.md:6` — "The chat suggestions (suggestion chips) should be the last 3 questions asked rather than supplied by env vars. The env var should be used to offer questions before any have been asked as a 'seed' for a new deployment." +**Story:** n/a (TODO-derived) + +## Objective +The onboarding chips become the 3 most recent user questions across saved chats (newest first, de-duplicated, cap 3); a fresh deployment with zero saved questions gets the seed list (`BOR_SUGGESTIONS` / the built-in default). + +## Work +1. `app/api/suggestions.py` — the endpoint gains `db: Session = Depends(get_db)` (import from `app.db` — the house pattern) and a module-level helper: + ```python + def last_questions(db: Session, limit: int = 3) -> list[str]: + ``` + - query `SavedChat` ordered by `updated_at.desc(), created_at.desc()` (the tiebreak — deterministic when timestamps collide; `from app.models import SavedChat`); + - for each chat, walk `chat.messages` in REVERSE (conversational order is oldest→newest — the `bor.chat.v1` shape) collecting `str(m.get("text", "")).strip()` for entries where `m.get("who") == "user"`; skip blanks; + - de-dup EXACT (case-sensitive) against the collected window; stop once `limit` unique texts are collected; return in encounter order (newest first). + - docstring: the JSONB column deserializes to a Python list of dicts (no SQL JSON ops — the `SavedChat.messages` model docstring says the record shape is the `bor.chat.v1` list); the exact-dedup choice is documented (case-insensitive would drop a legitimately differently-cased re-ask); the helper is pure-DB (unit-testable without the endpoint). + - endpoint body: `qs = last_questions(db)` → `return SuggestionList(suggestions=qs if qs else get_settings().suggestions)` — update the module/endpoint docstring: this endpoint owns the "last-3-questions-or-seed" contract; the deflection "Maybe try" chips (`app.rag.suggestions.derive_suggestions`) are a separate contract, untouched. + - note: phase 79 gates this endpoint with `require_user` — if phase 79 has NOT landed yet when this task runs (it is queued before this phase, so it has), the endpoint already carries the dependency; do not remove it. +2. `tests/integration/test_suggestions_api.py` (new — the house integration pattern, admin sign-in first — the endpoint is authed): + - **empty DB** (no saved chats) → exactly the built-in default list (assert equality with `get_settings().suggestions` — and `tests/unit/test_config.py` keeps pinning that default); + - **seed override:** the `BOR_SUGGESTIONS` JSON parsing is ALREADY pinned at unit level by `tests/unit/test_config.py::test_suggestions_env_override_is_json_list` (`monkeypatch.setenv("BOR_SUGGESTIONS", json.dumps(…))`) — do NOT hack per-test env into the integration app; the integration contract is the env-agnostic one below it (empty DB → exactly `get_settings().suggestions`, whatever the environment makes that); + - **cap + order:** one saved chat with 4 user questions q1..q4 (plus brain replies between them) → chips == `[q4, q3, q2]` (newest first, cap 3); + - **chat order:** two saved chats with DISTINCT `updated_at` (set the timestamps explicitly on the rows) → the newer chat's questions are walked first — a question from the newer chat outranks a newer-LOOKING question from the older chat; + - **dedup:** the same question text asked in two chats → appears exactly once; + - **partial:** exactly 2 saved questions deployment-wide → exactly 2 chips (NO seed top-up — the A6 contract); + - **brain-only:** a chat whose messages are all `who == "brain"` (or blank user texts) → contributes nothing; an all-brain deployment → the seed. + - anonymous → 401 (phase-79 contract — one assertion so the auth state of this endpoint is pinned HERE too). + +## Testing & Quality +- Integration: item 2 (every branch of `last_questions` + the fallback + the auth pin). +- Coverage: **>90%** on the modified `app/api/suggestions.py` (the helper's every branch: empty, partial, cap, dedup, blank-skip, brain-skip). + +## Completion Criteria +- [ ] `GET /api/suggestions` (authed) returns exactly the designed contract in every state of item 2. +- [ ] `app/rag/suggestions.py` (`derive_suggestions`) is UNTOUCHED and its tests green; the deflection "Maybe try" E2E behavior unchanged. +- [ ] `uv run ruff check . && uv run pyright` clean — the gate runs after this task. diff --git a/.agents/phases/todo/80_history_suggestion_chips/02_seed_semantics_docs.md b/.agents/phases/todo/80_history_suggestion_chips/02_seed_semantics_docs.md new file mode 100644 index 0000000..e01cf1a --- /dev/null +++ b/.agents/phases/todo/80_history_suggestion_chips/02_seed_semantics_docs.md @@ -0,0 +1,20 @@ +# Task 02 — Document the seed semantics (config, `.env.example`, README) + +**Phase:** `80_history_suggestion_chips` · **Source:** `TODO.md:6` +**Story:** n/a (TODO-derived) + +## Objective +The docs describe `BOR_SUGGESTIONS` as what it now is: the pre-first-question SEED — not "the" onboarding chips. + +## Work +1. `app/config.py` — the comment block above `suggestions: list[str]` becomes: "Onboarding-chip SEED (phase 80, TODO.md L6): shown ONLY while no saved chat has ever asked a question — after that, `GET /api/suggestions` serves the last 3 questions asked (deployment-wide, newest first). `BOR_SUGGESTIONS` overrides this seed for a new deployment." +2. `.env.example` (line ~55) — the comment becomes: `# BOR_SUGGESTIONS=["How is my Kubernetes cluster set up?"] # JSON seed chips — shown only before any question has been saved (phase 80)` +3. `README.md` — the env-table row (`BOR_SUGGESTIONS`, ~line 782): "JSON seed for the onboarding chips — shown only before the first saved question; afterwards the chips are the last 3 questions asked (phase 80)". +4. `README.md` — wherever the chat / suggestion-chip feature is described (the feature list row ~line 263 and the deflection note ~line 829 stay accurate — the deflection chips are UNCHANGED; add/adjust ONE line in the chat feature description: the onboarding chips follow the last 3 questions asked, seeding from `BOR_SUGGESTIONS` on a fresh deployment). + +## Testing & Quality +- Docs only — `tests/unit/test_config.py` and the stale-copy suites must stay green (no behavior change; the `suggestions` default list itself is UNTOUCHED). + +## Completion Criteria +- [ ] The three doc sites (config, `.env.example`, README) agree with the implemented contract. +- [ ] Full suite green; `uv run ruff check . && uv run pyright` clean. diff --git a/.agents/phases/todo/80_history_suggestion_chips/03_chips_new_chat_refetch.md b/.agents/phases/todo/80_history_suggestion_chips/03_chips_new_chat_refetch.md new file mode 100644 index 0000000..bd13e56 --- /dev/null +++ b/.agents/phases/todo/80_history_suggestion_chips/03_chips_new_chat_refetch.md @@ -0,0 +1,21 @@ +# Task 03 — The chips refresh when the empty state comes back (New chat) + +**Phase:** `80_history_suggestion_chips` · **Source:** `TODO.md:6` +**Story:** n/a (TODO-derived) + +## Objective +The onboarding row is fetched once at boot; after "New chat" (or clearing a restored conversation) the empty state returns with STALE chips — the last-3 state moved on while the user was chatting. Refetch on `bor:new-chat` so the row always reflects the current last-3 state. + +## Work +1. `frontend/assets/app.js` — in `startNewChat()` (the `bor:new-chat` handler, ~line 1848): after `if (emptyState) emptyState.hidden = false;`, add `loadSuggestions();` — the existing function (fetch `/api/suggestions` → `renderChips` into `#suggestions`, which clears the previous chips in place; progressive enhancement — swallows its own failures, no error spam). The in-flight-turn guard at the top of `startNewChat` means the refetch only runs for a real new chat. + - The boot path is UNCHANGED: `loadSuggestions()` still runs at shell boot (first paint of the empty state). The `/?chat=` boot opens a saved chat (empty state hidden) — when the user then clicks New chat, this refetch covers it. No other frontend change: the chips' one-tap submit, `role="list"` semantics, and the "Maybe try" deflection row are existing contracts. +2. Source pin (house pattern — read the JS source, no browser): in the app.js source-pin file that covers the new-chat flow (find where `bor:new-chat` / `startNewChat` is pinned today — `tests/unit/test_chat_persistence.py` or a `test_frontend_*.py` sibling; if none exists, add the pin to the most app.js-adjacent frontend source-pin file): `startNewChat` calls `loadSuggestions()` (the two literals, `startNewChat`'s function body containing the `loadSuggestions()` call — a containment assertion on the function's source slice, the house style). + +## Testing & Quality +- Unit: item 2 (the source pin). +- E2E: covered by the task-04 suite (the new-chat refetch assertion). +- Coverage: n/a (frontend) — the `app/` floor preserved. + +## Completion Criteria +- [ ] After New chat, `#suggestions` reflects a FRESH `/api/suggestions` response (the Playwright request log shows a second GET after the boot fetch). +- [ ] The source pin is green; `uv run ruff check . && uv run pyright` clean — the gate runs after this task. diff --git a/.agents/phases/todo/80_history_suggestion_chips/04_e2e_suite_commit.md b/.agents/phases/todo/80_history_suggestion_chips/04_e2e_suite_commit.md new file mode 100644 index 0000000..7b83e58 --- /dev/null +++ b/.agents/phases/todo/80_history_suggestion_chips/04_e2e_suite_commit.md @@ -0,0 +1,27 @@ +# Task 04 — Rewrite the story suite to the new semantics + sweep + the commit + +**Phase:** `80_history_suggestion_chips` · **Source:** `TODO.md:6` +**Story:** n/a (TODO-derived) + +## Objective +`tests/e2e/test_suggestion_chips.py` pins the NEW contract (the phase-76 precedent — a semantic change rewrites the story suite in place), the full pipeline is green, and the phase closes. + +## Work +1. `tests/e2e/test_suggestion_chips.py` — REWRITE (keep the file name — one suite per story, run in isolation; the endpoint is authed, so sign in as admin first via `auth_helpers.login`): + - **seed state:** fresh DB (no saved chats) → the chip texts equal the built-in default list — assert against a test-local constant copied from the `Settings.suggestions` default in `app/config.py` (the unit suite `test_config.py` pins only the SHAPE — ≥3 non-blank distinct strings — so this E2E literal is the pin for the exact seed list; keep it in sync with the config default); the chips render in `#suggestions` (role="list", the chip buttons) exactly as today. + - **last-3 state:** as admin, save two chats via `POST /api/chats` with known distinct questions (5 user questions total; set `updated_at` apart so the order is deterministic — the API stamps it; save the older one first) → a fresh page load → the chips are EXACTLY the 3 newest questions, in newest-first order. + - **partial state:** a DB with exactly 2 saved questions → exactly 2 chips (no seed top-up — the A6 contract, visible in the UI). + - **new-chat refetch:** load the page with the seed chips visible → via the API save a chat whose newest question is Q → click New chat (`#new-chat-btn`) → the chips now include Q (the refetch happened — the request log shows the second `GET /api/suggestions`). + - **carry over the story behavior** (unchanged semantics, same assertions as the old suite where they still hold): one-tap submit (chip click → composer filled → submitted — the mock-LLM brain bubble), Tab+Enter keyboard reachability of the chips (the original suite's keyboard-walk assertion). + - Run in isolation until green: `uv run pytest tests/e2e/test_suggestion_chips.py -v --no-cov`. +2. Full gate: `uv run pytest --cov=app --cov-report=term-missing` (>90%), `uv run ruff check . && uv run pyright`; the deflection-related suites green UNCHANGED (their chips are the LLM/title path — find them: `test_honest_deflection.py` and any "Maybe try" assertions — they must not have been touched by this phase). +3. ONE atomic `--no-gpg-sign` Conventional-Commits commit — e.g. `feat(chat): onboarding chips are the last 3 questions asked; the env seed only before the first` — body cites TODO.md L6 + the A6/A7 decisions (deployment-wide, exact dedup, no mixing, deflection untouched). Move the phase dir to `.agents/phases/complete/`. + +## Testing & Quality +- The full suite IS the test; coverage **>90%** on `app/`. +- E2E: the rewritten story suite in isolation (AGENTS.md rule 9). + +## Completion Criteria +- [ ] `uv run pytest tests/e2e/test_suggestion_chips.py -v --no-cov` green in isolation — all four states (seed / last-3 / partial / refetch) + the carried-over story behavior. +- [ ] Full suite green, coverage >90%, `uv run ruff check . && uv run pyright` clean. +- [ ] Committed; phase dir in `.agents/phases/complete/`.