refactor(agents): migrate .agent/ planning tree to .agents/

Standardize on the .agents/ directory (shared with project skills): phases/, user_stories/, reports/, screenshots/, validate.sh, and phase-sessions/ + pipeline.log all move to .agents/ (git mv preserves history; runtime artifacts move alongside). Updates every reference in AGENTS.md, README.md, .gitignore, app docstrings, and test story headers. Historical KB content in data/ and the runtime pipeline.log transcript are left untouched.
2026-09-05 10:57:07 -04:00
parent 766702c750
commit dbf2af26c6
1118 changed files with 664 additions and 664 deletions
@@ -0,0 +1,24 @@
+Everything is verified and green. Here's the report:
+
+**Phase 21 — Thinking Window: No Scroll Back, Just Live**
+
+**Implemented/Verified:**
+- CSS: `details.thinking .thinking-text` uses `overflow-y: hidden` (not `auto`), `max-height: 320px`, with owner-choice comment
+- JS bottom-pin (`textEl.scrollTop = textEl.scrollHeight`) verified intact — no JS change needed
+- Unit test: `tests/unit/test_thinking_no_scroll.py` (4 tests — CSS contract + JS pin pins)
+- E2E story: `tests/e2e/test_thinking_no_scroll.py` (5 tests — no user scroll, live tail tracking, CSS contract, answer bubble still scrollable, collapsed restore unaffected)
+- Story file: `.agents/user_stories/thinking-no-scroll.md`
+- Phase report: `.agents/reports/21_thinking_no_scroll/phase_report.md`
+- Atomic commit already made
+
+**Test/Lint/Coverage Results:**
+- `uv run pytest tests/unit/test_thinking_no_scroll.py -v --no-cov` → 4/4 passed
+- `uv run pytest tests/e2e/test_thinking_no_scroll.py -v --no-cov` → 5/5 passed (isolation)
+- `uv run pytest tests/e2e/test_thinking_display.py -v --no-cov` → 5/5 passed (regression)
+- `uv run pytest tests/e2e/test_long_answers.py -v --no-cov` → 2/2 passed (regression)
+- `uv run pytest --cov=app --cov-report=term-missing` → 319 passed, 99% coverage
+- `uv run ruff check . && uv run pyright` → clean (0 errors)
+
+**Completion Criteria:** All 8 criteria met ✅
+
+**Next pending phase:** Phase 24 (whole-document context, A7 revised) — per roadmap §12.
@@ -0,0 +1,46 @@
+........................................................................ [ 22%]
+........................................................................ [ 45%]
+........................................................................ [ 67%]
+........................................................................ [ 90%]
+...............................                                          [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                     Stmts   Miss  Cover
+--------------------------------------------
+app/__init__.py              1      0   100%
+app/api/__init__.py          0      0   100%
+app/api/auth.py             22      0   100%
+app/api/chat.py             95      0   100%
+app/api/docs.py             23      0   100%
+app/api/health.py           10      0   100%
+app/api/steering.py         33      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               56      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/debugging.py       29      2    93%
+app/core/logging.py         13      0   100%
+app/db.py                   21      0   100%
+app/main.py                 36      0   100%
+app/models.py               46      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        150      5    97%
+app/rag/llm.py             105      0   100%
+app/rag/prompts.py          44      0   100%
+app/rag/retriever.py       102      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1109     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,13 @@
+The pre-existing unstaged deletions under `.agents/phases/todo/20_*` are harness phase-management state (phase 20's move to `complete/`), not mine — I leave them untouched per the rules, and no commit belongs to task 01 (the atomic commit is task 02's step). All task-01 criteria are met.
+
+**Task 01 report — `.thinking-text` overflow hidden (no user scroll)**
+
+- `frontend/assets/styles.css`: `details.thinking .thinking-text` → `overflow-y: hidden` (was `auto`), `max-height: 320px` kept, owner-choice comment added (2026-08-24, "live tail only — the JS bottom-pin is the sole scroller"); leading comment "scrollable"→"live-tail" for accuracy
+- `frontend/assets/app.js`: **unchanged** — verified the phase-17 pin `textEl.scrollTop = textEl.scrollHeight` intact (line 899, inside the `block.open` guard)
+- New `tests/unit/test_thinking_no_scroll.py` (4 tests): CSS rule pins (`overflow-y: hidden` + `max-height: 320px`, no `auto`), owner-choice comment, pin present exactly once in the streaming thinking branch, no new scroll machinery in app.js
+- Adapted stale pin in `tests/unit/test_chat_persistence.py` (asserted the old `overflow-y: auto`) — required "adapted regression" per phase 21
+- Manual smoke (real mock-LLM stream, headless Chromium, temp suite deleted after): computed style `overflow-y: hidden`/`320px`; live pin ≤1px from bottom on every 30ms sample; forced 1200px overflow → wheel cannot move it, programmatic pin still works; element not keyboard-focusable; answer bubble regression intact
+- `uv run pytest` → 319 passed; `uv run pytest --cov=app` → 99% (>90% gate); `uv run ruff check . && uv run pyright` → clean (0 errors)
+- Regression E2E in isolation: `test_thinking_display.py` 5/5, `test_long_answers.py` 2/2, `test_follow_bottom_scroll.py` 5/5
+- Note: pre-existing unstaged deletions of `todo/20_*` files are harness state; not touched, no commit made (commit is task 02's)
+- Next pending task: `.agents/phases/todo/21_thinking_no_scroll/02_e2e_story_suite_commit.md`
@@ -0,0 +1,46 @@
+........................................................................ [ 22%]
+........................................................................ [ 45%]
+........................................................................ [ 67%]
+........................................................................ [ 90%]
+...............................                                          [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                     Stmts   Miss  Cover
+--------------------------------------------
+app/__init__.py              1      0   100%
+app/api/__init__.py          0      0   100%
+app/api/auth.py             22      0   100%
+app/api/chat.py             95      0   100%
+app/api/docs.py             23      0   100%
+app/api/health.py           10      0   100%
+app/api/steering.py         33      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               56      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/debugging.py       29      2    93%
+app/core/logging.py         13      0   100%
+app/db.py                   21      0   100%
+app/main.py                 36      0   100%
+app/models.py               46      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        150      5    97%
+app/rag/llm.py             105      0   100%
+app/rag/prompts.py          44      0   100%
+app/rag/retriever.py       102      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1109     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,27 @@
+Here is the final report:
+
+---
+
+**Implemented:**
+- `tests/e2e/test_thinking_no_scroll.py` — 5 E2E tests (already existed, verified green)
+  1. `test_thinking_window_not_user_scrollable` — wheel/drag/keyboard on frozen live tail don't move the window
+  2. `test_thinking_window_tracks_live_tail` — per-chunk pin keeps window at tail; last chunk visible
+  3. `test_thinking_window_css_contract` — `overflow-y: hidden`, `max-height: 320px`, real clip
+  4. `test_answer_bubble_still_scrollable` (phase 11 regression) — answer bubble untouched
+  5. `test_restored_collapsed_thinking_unaffected` (phase 17 regression) — stored thinking restores collapsed
+- `.agents/user_stories/thinking-no-scroll.md` — story file (created)
+- `.agents/reports/21_thinking_no_scroll/phase_report.md` — phase report (created)
+- Atomic commit: `fix(ui): thinking window no longer scrolls — live 320px view pinned to the stream tail`
+
+**Test / lint / coverage results:**
+- `uv run pytest tests/e2e/test_thinking_no_scroll.py -v --no-cov` → **5/5 passed**
+- `uv run pytest tests/e2e/test_thinking_display.py -v --no-cov` → **5/5 passed**
+- `uv run pytest tests/e2e/test_long_answers.py -v --no-cov` → **2/2 passed**
+- `uv run pytest --no-cov` → **319 passed**
+- `uv run pytest --cov=app --cov-report=term-missing` → **99%** (gate: >90%)
+- `uv run ruff check .` → **All checks passed**
+- `uv run pyright` → **0 errors, 0 warnings**
+
+**Notable decisions:** No deviations. The CSS-only change (`overflow-y: hidden`) works because the phase-17 JS bottom-pin (`scrollTop = scrollHeight`) still functions under `hidden`. No JS changes needed.
+
+**Next pending task:** `.agents/phases/todo/22_background_animation/` (Phase 22 — background animation)
@@ -0,0 +1,46 @@
+........................................................................ [ 22%]
+........................................................................ [ 45%]
+........................................................................ [ 67%]
+........................................................................ [ 90%]
+...............................                                          [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                     Stmts   Miss  Cover
+--------------------------------------------
+app/__init__.py              1      0   100%
+app/api/__init__.py          0      0   100%
+app/api/auth.py             22      0   100%
+app/api/chat.py             95      0   100%
+app/api/docs.py             23      0   100%
+app/api/health.py           10      0   100%
+app/api/steering.py         33      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               56      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/debugging.py       29      2    93%
+app/core/logging.py         13      0   100%
+app/db.py                   21      0   100%
+app/main.py                 36      0   100%
+app/models.py               46      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        150      5    97%
+app/rag/llm.py             105      0   100%
+app/rag/prompts.py          44      0   100%
+app/rag/retriever.py       102      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1109     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK