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,17 @@
+Phase 26 final verification pass — all criteria verified, no defects found, repo left green.
+
+**Verified (all tasks 01–04 in `complete/`):**
+- Modal skeleton + `--doc-modal-*` CSS in `index.html`/`sources.html` (96vw×92vh panel, rgba backdrop, no blur, reduced-motion safe); `document-modal.js` single owner; chips/row-links intercepted; `document.js` exports `renderDocument`; standalone `/document.html` untouched.
+- UI probe: `.doc-md` inside modal = 736px (46rem cap), centered; backdrop behind panel; 360px viewport → no horizontal overflow (scrollWidth 360 = clientWidth), panel 345.6×588.8 fits.
+
+**Test / lint / coverage:**
+- `uv run pytest --cov=app --cov-report=term-missing` → 352 passed, TOTAL **99%** (>90% gate; `app/` untouched by this phase)
+- `uv run pytest tests/e2e/test_document_viewer.py -v --no-cov` → **7 passed** in isolation
+- Regressions in isolation: `test_document_back_navigation` 3✓, `test_header_consistency` 3✓, `test_smoke` 3✓, plus every other chip-touching suite (admin_auth, chat_persistence, chat_rag, dark_tech_theme, long_answers, retrieval_quality, sources_midstream_bug, thinking_display, whole_document_context) all passed
+- `uv run ruff check . && uv run pyright` → clean (0 errors, 0 warnings)
+
+**Completion criteria:** modal open same-page no-tab ✓; same content as viewer (md/`pre.doc-raw`/meta) ✓; close button/Escape/backdrop + a11y frame ✓; `/document.html` unchanged ✓; no CDN (grep + E2E asset assertions) ✓; pytest+coverage ✓; story E2E isolation ✓; ruff+pyright ✓; UI structure check ✓; `document-modal.md` exists ✓; commit + phase move = **harness commit point** (`PHASE_COMMIT`), not performed by executor per protocol.
+
+**Notable:** no defects found; `TODO.md` working-tree edit (roadmap note removal) pre-existed this pass and was left as-is; no `app/` change (honours the no-backend-change lock).
+
+**Next pending phase:** `27_global_tuning` (then `28_git_based_sources`).
@@ -0,0 +1,46 @@
+........................................................................ [ 20%]
+........................................................................ [ 40%]
+........................................................................ [ 61%]
+........................................................................ [ 81%]
+................................................................         [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               55      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        93      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1099     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,15 @@
+Task 01 complete. All green.
+
+**Implemented**
+- `frontend/index.html`: `.doc-modal` skeleton before `</body>` — backdrop, `role="dialog"` panel, sticky header (title, "Full page" link, close button), `aria-live` meta row, visually-hidden status, scrollable `<main>` content; all documented ids incl. `#doc-modal-panel` (required by the task's completion criteria)
+- `frontend/assets/styles.css`: new "Document modal (phase 26)" section — `position:fixed; inset:0; z-index:1000`; backdrop `rgba(10,14,23,.82)` (no blur, 120ms opacity transition); panel `min(1100px,96vw) × 92vh` centered via `margin:auto`; header pinned to `--header-h` (64/58px) with ellipsizing title; ≥44px close/open controls (ghost pill + err-hover, 3px focus-visible); meta reuses viewer badge classes with wrap; `.doc-modal[hidden]{display:none}`; ≤640px squeeze rules (icon-only Full-page pill); `prefers-reduced-motion` kills the transition
+
+**Verification**
+- `uv run pytest --cov=app --cov-report=term-missing` → 331 passed, TOTAL **99%** (frontend-only, no `app/` delta)
+- `uv run ruff check .` → clean · `uv run pyright` → 0 errors
+- `uv run pytest tests/e2e/test_document_viewer.py -v --no-cov` → 5 passed in isolation (no regression; page unchanged)
+- Playwright UI check: 1100×828 / 345.6×680.8 panels, header 64/58px, 46rem md column centered (736px), in-panel scroll only, body overflow 0 at 1440px and 360px, backdrop no-blur, reduced-motion transition 0s
+
+**Decisions** — added `id="doc-modal-panel"` beyond the Work-skeleton (the task's own completion criteria list it; skeleton otherwise verbatim); no scroll-lock on body (not in contract — left to task 02's JS).
+
+**Next pending task:** `02_app_js_modal_intercept.md`
@@ -0,0 +1,46 @@
+........................................................................ [ 20%]
+........................................................................ [ 41%]
+........................................................................ [ 62%]
+........................................................................ [ 83%]
+.........................................................                [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               55      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        93      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1099     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,24 @@
+Everything is green and consistent. Final state verified — the complete gate set:
+
+- **Implemented**
+  - New `frontend/assets/document-modal.js` — single owner of the modal (mirrors `header.js`): `openDocumentModal(source, path, triggerEl)` / `closeDocumentModal()`; fetches `/api/documents/content` (same encoding as the page), renders through the shared renderer, not-found line on `!ok`/network error; closes on button, backdrop click, and Escape (document-captured); Tab/Shift+Tab focus trap; focus moves into `#doc-modal-content` on open and returns to the trigger on close (best-effort); "Full page" link rebuilt to the `/document.html?source=…&path=…` URL on open; stale-fetch guard for rapid open/close.
+  - `frontend/assets/document.js` — extracted `export renderDocument(doc, { titleEl, metaEl, containerEl })` (escape-first contract kept: `innerHTML` only via `renderMarkdown`, raw via `textContent`); the `/document.html`-specific init (back link, whoami, New Chat, `load()`) now runs only under a `#doc-title` guard so the import is side-effect-free on chat/Sources pages.
+  - `frontend/assets/app.js` — source chips: `target="_blank"`/`rel` removed, left-click intercepted → `openDocumentModal(s.source, s.path, chip)`; `href` (encoded `documentUrl`, unchanged output) + title/aria-truncation kept as no-JS/context-menu escape hatch.
+  - `frontend/assets/sources.js` — same interception for `.doc-link` rows → `openDocumentModal(d.source, d.path, link)`.
+  - `frontend/sources.html` — same modal skeleton as `index.html` (byte-identical, verified by diff) **and** `markdown.js` loaded before the module script (was missing — the modal couldn't render md on Sources otherwise).
+  - **Pre-existing defect fixed** (found via live browser check): `readSSE` never released the reader lock, so `res.body.cancel()` in the turn's `finally` produced an unhandled rejection ("Cannot cancel a locked stream" pageerror) on *every* completed chat turn — now `reader.releaseLock()` + rejection-safe `cancelStream()`.
+  - Tests: `tests/unit/test_document_viewer.py` — adapted the old new-tab contract test + 6 new phase-26 pins (renderer export/import, import-safety guard, skeletons on both pages, sources.html markdown ordering, modal close/focus/URL pins, node behavioral URL-encoding check); `tests/integration/test_api.py` — new asset served; `tests/e2e/test_chat_rag.py` + `test_chat_persistence.py` — stale `target="_blank"` assertions adapted to the no-new-tab contract (not in task 04's scope).
+
+- **Test / lint / coverage**
+  - `uv run pytest` → **351 passed**
+  - `uv run pytest --cov=app --cov-report=term-missing` → **351 passed, TOTAL 99%** (app/ untouched, unchanged)
+  - `uv run ruff check . && uv run pyright` → **clean (0 errors)**
+  - Live-browser verification (throwaway Playwright suite, deleted after): chip → same-page modal (`.doc-md`, focus, Full-page href, meta badges, Escape/backdrop/button close, focus restore, **zero page errors**); Sources row → modal (`.doc-raw` yaml, focus restore); `/document.html` unchanged (title/md, `back` param, not-found).
+  - E2E regressions run in isolation: `test_smoke`, `test_header_consistency`, `test_chat_rag`, `test_loading_feedback`, `test_thinking_display`, `test_chat_persistence` → **all green**.
+
+- **Decisions / deviations**
+  - `document-modal.js` loads via relative import from the page scripts only — **no direct `<script>` tag** — to honor the Containerfile single-evaluation pins (`test_containerfile_assets.py`), matching the `header.js` design the task cites.
+  - `test_document_viewer.py` (E2E) and `test_document_back_navigation.py` still assert the old new-tab behavior — deliberately left as-is: task 04's file explicitly rewrites/adapts them.
+  - Task file/phase files untouched; `.agents/user_stories/document-modal.md` already exists.
+
+- **Next pending task:** `.agents/phases/todo/26_document_modal_viewer/03_document_js_modal_mode.md`
@@ -0,0 +1,46 @@
+........................................................................ [ 20%]
+........................................................................ [ 41%]
+........................................................................ [ 61%]
+........................................................................ [ 82%]
+...............................................................          [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               55      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        93      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1099     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,22 @@
+All gates confirmed green. Final report:
+
+## Task 03 — `document.js` shared `renderDocument` (modal mode) — COMPLETE
+
+**Implemented**
+- `frontend/assets/document.js`: `renderDocument` now carries task 03's exact signature `renderDocument(doc, { titleEl, metaEl, contentEl })` (renamed from task 02's `containerEl`); the page's `load()` path calls it with the page's `#doc-title`/`#doc-meta`/`#doc-content`; everything else (query-param parsing, `back` target, not-found card, shared header, New Chat, `mainEl.focus()`) unchanged.
+- `frontend/assets/document-modal.js`: fetch handler now calls `renderDocument(doc, { titleEl, metaEl, contentEl })` with `#doc-modal-title`/`#doc-modal-meta`/`#doc-modal-content`; `#doc-modal-open` still gets the `/document.html?source=…&path=…` URL on open.
+- `tests/unit/test_document_viewer.py`: pinned the exact task-03 signature (export + page call + modal call).
+- No new unit/integration tests required (task: frontend-only refactor); no-CDN test passes unchanged (no new tags — see deviation).
+
+**Test / lint / coverage**
+- `uv run pytest tests/unit tests/integration` → **351 passed** (exit 0)
+- `uv run pytest --cov=app --cov-report=term-missing` → **TOTAL 99%** (1099 stmts, gate >90%)
+- `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors
+- E2E (full dir, one pass): green except **4 known-stale popup-contract tests** (2× `test_document_viewer.py`, 2× `test_document_back_navigation.py`) — exactly what task 04 rewrites/adapts; standalone-page viewer tests 3/4/5 pass. `test_chat_rag` (3), `test_chat_persistence` (4), `test_shared_header` (6) green in isolation.
+- Real-browser check (throwaway, since deleted): chip→modal (md via `.doc-md`), Escape closes + focus restored, Sources link→modal (yaml `.doc-raw`), backdrop closes, standalone page unchanged — **zero console/page errors on all three pages**.
+
+**Deviations**
+- Task 03 steps 3–4 (literal `<script type="module" src="/assets/document-modal.js">` tags) **not added**: task 02's completed design loads the modal via the page scripts' import graph, its unit test *forbids* direct tags, and in the prod image the page scripts are esbuild bundles with the modal inlined (a tag would 404 or fork module state → leaked Escape/Tab listener, lost focus restore). The module is genuinely loaded on both pages (browser-verified) — the criterion is met in the only form the project's tests allow.
+- No commit: one atomic `--no-gpg-sign` commit is the *phase* completion criterion (task 4 of 4).
+
+**Next pending task:** `.agents/phases/todo/26_document_modal_viewer/04_e2e_regression_suite.md`
@@ -0,0 +1,46 @@
+........................................................................ [ 20%]
+........................................................................ [ 41%]
+........................................................................ [ 61%]
+........................................................................ [ 82%]
+...............................................................          [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               55      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        93      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1099     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+**Task 04 complete — all gates green.**
+
+**Implemented**
+- Rewrote `tests/e2e/test_document_viewer.py` for the modal contract (7 tests, seeding harness unchanged): chip→modal in-page (no popup, URL unchanged, `min(1100px,96vw)×92vh` panel, `.doc-md` + meta), Sources row→modal (yaml in mono `pre.doc-raw`), close via button/backdrop/Escape, focus-in-`#doc-modal-content` + `role=dialog`/`aria-modal`/aria-label + focus-restore, XSS-safe modal render, standalone `/document.html` phase-10 contract kept, dark theme + Phase-08 surface + no-CDN.
+- Adapted `tests/e2e/test_document_back_navigation.py`: chips/links no longer open tabs (phase 26) — back contract now verified through the exact `href` each link still carries (no-JS/new-tab escape hatch); malicious-back test unchanged.
+- `tests/integration/test_api.py`: no-CDN test counts no script tags (no bump needed); added `/assets/document-modal.js` to the all-assets emoji guard.
+- `.agents/user_stories/document-modal.md` verified present, mapping 1:1 to the 7 E2E scenarios.
+
+**Results**
+- `uv run pytest tests/e2e/test_document_viewer.py -v --no-cov` → 7 passed (isolation)
+- `test_document_back_navigation` / `test_header_consistency` / `test_smoke` → 3+3+3 passed (each isolated)
+- `uv run pytest --cov=app --cov-report=term-missing` → 352 passed, TOTAL 99% (= pre-change 99%)
+- `uv run ruff check . && uv run pyright` → clean (fixed a `str|None` pyright error introduced by the adaptation)
+
+**Notes:** one test fix during dev — panel width is `min(1100px, 96vw)` per task-01 CSS, so the desktop assertion uses 1100px. No app/ changes → no coverage delta. Commit left to the harness (task/phase files untouched per protocol).
+
+**Next pending task:** `27_global_tuning/01_steering_put_endpoint.md`.
@@ -0,0 +1,46 @@
+........................................................................ [ 20%]
+........................................................................ [ 40%]
+........................................................................ [ 61%]
+........................................................................ [ 81%]
+................................................................         [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               55      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        93      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1099     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK