chore(agent): track .agent/ planning tree in git

Remove the blanket .agent/ gitignore so the phase roadmap, user stories, reports, and PLAN.md are versioned with the code. Only runtime artifacts (.agent/phase-sessions/, .agent/pipeline.log) remain ignored. Update AGENTS.md git protocol rule to match.
2026-09-01 10:18:22 -04:00
parent 5fa620fde5
commit 4971e2859d
818 changed files with 23964 additions and 4 deletions
@@ -0,0 +1,12 @@
+All done — the pgrep hits were my own shell. Final state verified: 672 docs / 8969 chunks in the DB, clean tree, commit `99c48cb`.
+
+---
+
+**Phase 02 (import documents) — complete**
+
+- **Code**: fence-aware chunker (1200-char hard cap, atomic fences, overlap+anchor); `LLMClient` reusing the openai client's httpx transport — openai SDK 1.x/2.x both inject `encoding_format`, which aipi's LiteLLM `openai_like` rejects (flagged deviation from A5's plain-SDK intent); token-budget batching + halving retry for aipi's ~1024-token per-request cap; two-phase per-file upsert (sha256 delta, atomic commit, A9 walk, prune, per-file error tolerance, adaptive re-chunk at half target for URL-dense files); `scripts/import_docs` CLI; `GET /api/docs`; Sources page wired to real endpoint (XSS-safe DOM rows).
+- **Real run**: `files=672 added=672 unchanged=0 pruned=0 errors=0 chunks=8969 embed_batches=2188` in ~3m; idempotent re-run: 672 unchanged, 0 batches. One file (URL-dense README) re-chunked at 1000 chars via the adaptive path.
+- **Gates**: 63 unit/integration passed, story E2E 3/3, ruff + pyright clean, coverage 98% (>90%), `.agent/validate.sh` → "validation OK".
+- **UI**: 1280px + 375px screenshots at `/tmp/bor_screenshots/` (full-width a11y table, stat cards, mono paths, designed empty state; no CDN).
+- **Fixes**: phase-01 harness defect (validate.sh used system python3) → now uv-gated, committed with `-f`.
+- **Commit**: `99c48cb feat(rag): index markdown KB — chunker, embed client, delta importer, Sources page`.
@@ -0,0 +1,34 @@
+.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/chat.py              7      0   100%
+app/api/docs.py             12      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               31      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               40      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         126      4    97%
+app/rag/importer.py        136      5    96%
+app/rag/llm.py              77      0   100%
+app/schemas.py              29      0   100%
+--------------------------------------------
+TOTAL                      568     11    98%
+coverage gate: app/ 98% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,5 @@
+No API key found for the selected model.
+
+Use /login to log into a provider via OAuth or API key. See:
+  /var/home/ducoterra/.nvm/versions/node/v24.18.0/lib/node_modules/@earendil-works/pi-coding-agent/docs/providers.md
+  /var/home/ducoterra/.nvm/versions/node/v24.18.0/lib/node_modules/@earendil-works/pi-coding-agent/docs/models.md
@@ -0,0 +1 @@
+(no final assistant message — see the .err log)
@@ -0,0 +1,21 @@
+ImportError while loading conftest '/var/home/ducoterra/Projects/Personal/brain_of_reese/tests/conftest.py'.
+tests/conftest.py:7: in <module>
+    from app.main import app as fastapi_app
+app/main.py:17: in <module>
+    from app.api.health import router as health_router
+app/api/health.py:7: in <module>
+    from app.db import db_available
+app/db.py:21: in <module>
+    engine = create_engine(get_settings().database_url, pool_pre_ping=True, future=True)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+../../../.local/lib/python3.14/site-packages/sqlalchemy/util/deprecations.py:281: in warned
+    return fn(*args, **kwargs)  # type: ignore[no-any-return]
+           ^^^^^^^^^^^^^^^^^^^
+../../../.local/lib/python3.14/site-packages/sqlalchemy/engine/create.py:617: in create_engine
+    dbapi = dbapi_meth(**dbapi_args)
+            ^^^^^^^^^^^^^^^^^^^^^^^^
+../../../.local/lib/python3.14/site-packages/sqlalchemy/dialects/postgresql/psycopg.py:495: in import_dbapi
+    import psycopg
+E   ModuleNotFoundError: No module named 'psycopg'
+All checks passed!
+validation FAILED (see output above)
@@ -0,0 +1,5 @@
+No API key found for the selected model.
+
+Use /login to log into a provider via OAuth or API key. See:
+  /var/home/ducoterra/.nvm/versions/node/v24.18.0/lib/node_modules/@earendil-works/pi-coding-agent/docs/providers.md
+  /var/home/ducoterra/.nvm/versions/node/v24.18.0/lib/node_modules/@earendil-works/pi-coding-agent/docs/models.md
@@ -0,0 +1 @@
+(no final assistant message — see the .err log)
@@ -0,0 +1,21 @@
+ImportError while loading conftest '/var/home/ducoterra/Projects/Personal/brain_of_reese/tests/conftest.py'.
+tests/conftest.py:7: in <module>
+    from app.main import app as fastapi_app
+app/main.py:17: in <module>
+    from app.api.health import router as health_router
+app/api/health.py:7: in <module>
+    from app.db import db_available
+app/db.py:21: in <module>
+    engine = create_engine(get_settings().database_url, pool_pre_ping=True, future=True)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+../../../.local/lib/python3.14/site-packages/sqlalchemy/util/deprecations.py:281: in warned
+    return fn(*args, **kwargs)  # type: ignore[no-any-return]
+           ^^^^^^^^^^^^^^^^^^^
+../../../.local/lib/python3.14/site-packages/sqlalchemy/engine/create.py:617: in create_engine
+    dbapi = dbapi_meth(**dbapi_args)
+            ^^^^^^^^^^^^^^^^^^^^^^^^
+../../../.local/lib/python3.14/site-packages/sqlalchemy/dialects/postgresql/psycopg.py:495: in import_dbapi
+    import psycopg
+E   ModuleNotFoundError: No module named 'psycopg'
+All checks passed!
+validation FAILED (see output above)
@@ -0,0 +1,11 @@
+Phase 03 complete. Report:
+
+**Phase 03 — Story: Chat RAG Answer (happy path) — COMPLETE** (`396e4d4`)
+- Implemented: `app/rag/retriever.py` (cosine top-k → parent-doc selection, dedupe, 20k-char cap w/ `[…truncated…]`), `app/rag/prompts.py` (locked persona + HIGH/DEFLECT builders), `LLMClient.chat_stream` (+`LLMError`), `POST /api/chat` SSE (delta*→done, query_log row, PLAN §9 log line, error event mid-stream, 503 JSON if DB down), UI SSE reader w/ live streaming, source chips→/sources.html, role=alert error banner, always-recovers Send state.
+- Tests: unit (retriever/prompts/SSE/llm) + integration (real Postgres turn, log row, error/503 + mid-turn failure paths) + new Playwright story suite (grounded answer, query_log, raw SSE shape); smoke placeholder test replaced with the real never-stale contract.
+- `uv run pytest --cov=app --cov-report=term-missing` → **95 passed, TOTAL 98%** (chat/llm/prompts/retriever 100%).
+- `uv run pytest tests/e2e/test_chat_rag.py -v --no-cov` (isolated) → **3 passed**; `test_smoke.py` → 3 passed; `test_import_documents.py` (regression) → 3 passed.
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors.
+- Fixed defect (scaffold): `.kb-banner` `display:flex` overrode the `hidden` attribute → banner always visible; added `[hidden]{display:none!important}` + regression assertion. UI verified at 1280px/375px + XSS-escape proof.
+- Deviations: happy-path scope per phase file — LOW-threshold deflection/amber mode intentionally deferred to phase 04 (HIGH/DEFLECT builders + `deflected` plumbing ready).
+- Next pending: `.agent/phases/todo/04_story_honest_deflection.md`.
@@ -0,0 +1,34 @@
+    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/chat.py             66      0   100%
+app/api/docs.py             12      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               31      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               40      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         126      4    97%
+app/rag/importer.py        136      5    96%
+app/rag/llm.py              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py        40      0   100%
+app/schemas.py              29      0   100%
+--------------------------------------------
+TOTAL                      699     11    98%
+coverage gate: app/ 98% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+Phase 04 complete — committed as `cbf8e39`.
+
+**Implemented**
+- Honesty gate (A8): `plan_turn()` in `app/api/chat.py` — `top_score < BOR_RELEVANCE_THRESHOLD` ⇒ LOW `DEFLECT_MODE` prompt (weak-hit titles only, never doc content), `deflected` on `done` event + `query_log`; empty KB now honestly deflects too
+- `app/rag/suggestions.py::derive_suggestions` — deterministic 2–3 "Maybe try" chips from weak-hit titles (fallback top-up from onboarding questions) + `retriever.weak_hit_titles()`
+- Frontend: amber `.is-deflected` bubble + accessible "Maybe try" chip group (`.suggestion-chip`, ≥44px, `role=list` + `aria-label`); click = fill + focus (submit behavior deferred to Phase 05 per phase spec)
+- README Troubleshooting: deflection behavior + `BOR_RELEVANCE_THRESHOLD` tuning (incl. 0.0/1.0 extremes)
+
+**Results (all green)**
+- `uv run pytest --cov=app --cov-report=term-missing` → 110 passed, **99%** on `app/` (>90% ✓)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+- `uv run pytest tests/e2e/test_honest_deflection.py -v --no-cov` → **3 passed** in isolation
+- Regressions: `test_chat_rag.py` 3✓, `test_smoke.py` 3✓, `test_import_documents.py` 3✓; UI verified at 1280px + 375px (amber #fff7e8/#f59e0b, chip contrast, clean mobile wrap)
+
+**Decisions:** strict `<` gate (0.30 ⇒ HIGH, per spec); weak hits still reported as `sources` on deflected turns; found & fixed a blank-title bug in suggestion derivation via the new unit tests; updated the stale empty-KB integration expectation (now deflected).
+
+**Next pending phase:** `05_story_suggestion_chips.md`
@@ -0,0 +1,34 @@
+
+-- 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/chat.py             82      0   100%
+app/api/docs.py             12      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               31      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               40      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         126      4    97%
+app/rag/importer.py        136      5    96%
+app/rag/llm.py              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py        49      0   100%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              29      0   100%
+--------------------------------------------
+TOTAL                      751     11    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,18 @@
+Phase 05 complete and committed (`2364e1e`).
+
+**Implemented**
+- `app.js`: extracted shared `renderChips(container, items, {onSelect})` + `submitSuggestion()` (fill → focus → `composer.requestSubmit()`); onboarding chips and "Maybe try" deflection chips now both one-tap-submit. Mobile CSS verified (existing tokens, no duplication); defaults confirmed against real Homelab/Deployments topics.
+- `.env.example`: documented `BOR_SUGGESTIONS` (JSON list; pydantic-settings override verified).
+- Tests: 3 new unit (default ≥3, JSON env override, malformed-JSON fails loudly), 1 new integration (endpoint honors `BOR_SUGGESTIONS` via fresh app), new E2E `tests/e2e/test_suggestion_chips.py` (render ≥3 from API, click submits, Tab+Enter, 375px scroll row).
+- Updated Phase 04 E2E `test_deflection_suggestions_are_clickable` to the new one-tap contract (shared component behavior change).
+
+**Gates (all green)**
+- `uv run pytest` → 114 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 99% (>90%)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+- `uv run pytest tests/e2e/test_suggestion_chips.py -v --no-cov` → 4 passed in isolation; regression: honest_deflection/chat_rag/import_documents/smoke all 3 passed
+- UI pass: 1280px + 375px screenshots verified (centered wrap vs single scroll row, 999px pills ≥44px, brand-soft/brand-ink ≈8.8:1, hover/active, "Suggested questions" group, chips gone after first message)
+
+**Decisions**: kept the story's 4 default suggestions (all map to real docs: kubernetes/k3s, Borg backup, Deployments, per-service inventory); deflection group keeps `aria-label="Maybe try"`/`role=list` for Phase 04 compatibility; commit also records the harness's 04→complete/ move.
+
+**Next pending phase**: `06_story_loading_feedback.md`
@@ -0,0 +1,34 @@
+
+-- 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/chat.py             82      0   100%
+app/api/docs.py             12      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               31      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               40      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         126      4    97%
+app/rag/importer.py        136      5    96%
+app/rag/llm.py              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py        49      0   100%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              29      0   100%
+--------------------------------------------
+TOTAL                      751     11    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+Phase 06 complete and committed (`e5810b0`).
+
+**Implemented**
+- `app.js`: single `setUiState(state)` state machine (`idle → thinking → streaming → done|error → idle`) driving typing indicator, button disabled/spinner/label, and `#send-status`; 10s elapsed-seconds aria-label hint; exported `TURN_TIMEOUT_MS = 120000` guard (cleared on first delta); error banner with actionable hint; reduced-motion-aware scrolling; ad-hoc `setBusy` removed
+- Server: `ChatErrorEvent` schema (exact `{type, detail}` SSE error wire shape) used in all 3 chat error branches; `embed_ms`/`total_ms` added to error-path logs (per-turn line already had both — confirmed)
+- Mock LLM: additive `POST /__shutdown__` hook; E2E `llm_down` fixture stops the mock and restores a fresh instance for later tests
+- Tests: SSE error-event serialization (unit + integration), frontend contract unit tests, `tests/e2e/test_loading_feedback.py` (5 tests: slow-think indicator, button machine, live streaming, reduced motion, LLM-down recovery)
+
+**Results**
+- `uv run ruff check .` → all checks passed; `uv run pyright` → 0 errors
+- `uv run pytest --cov=app --cov-report=term-missing` → 123 passed, coverage 99% (>90% gate)
+- `uv run pytest tests/e2e/test_loading_feedback.py -v --no-cov` → 5 passed in isolation
+- Regression check: all 5 prior story E2E suites re-run in isolation → 16 passed
+
+**Decisions**: no CSS changes needed (tokens + reduced-motion fallbacks already met spec); error→idle settles in the turn handler's `finally` so the banner persists while the button always recovers; committed only phase-06 files (`.agent/` file moves are harness-managed; the unrecorded phase-05 move predates this phase).
+
+**Next pending phase**: `.agent/phases/todo/07_story_responsive_polish.md`
@@ -0,0 +1,34 @@
+
+-- 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/chat.py             84      0   100%
+app/api/docs.py             12      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               31      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               40      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         126      4    97%
+app/rag/importer.py        136      5    96%
+app/rag/llm.py              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py        49      0   100%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              32      0   100%
+--------------------------------------------
+TOTAL                      756     11    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,11 @@
+Phase 07 complete. Report:
+
+**Phase 07 — Responsive, Polished, Accessible UI: done. Committed `1b29b1c`, tree clean, pipeline empty (`todo/` → 0).**
+
+- **Fixed 4 real deviations found by the sweep:** (1) skip-link target `<main>` wasn't focusable → added `tabindex="-1"` on both pages; (2) `.composer textarea:focus { outline: none }` suppressed the `:focus-visible` ring → removed; (3) long unbreakable tokens blew out the chat column → `min-width: 0` on `.msg-body`/`.source-chip`; (4) deflection "Maybe try" chips (445px) overflowed 375px phones → `min-width:0; max-width:100%` on `.maybe-try .suggestion-chip` (text now wraps in-pill; onboarding scroll row untouched).
+- **New E2E suite** `tests/e2e/test_responsive_polish.py` — 7 tests (the 6 mapped + long-content): overflow-free at 360/375/768/1280/1600 both pages, 46rem centered cap at 1600, Sources table ≥80% width at 1280, landmarks/skip-link/labels/keyboard walk, computed WCAG contrast ≥4.5:1, reduced-motion, 60-char token wrap. **7/7 pass in isolation.**
+- **No-CDN re-verification** extended to `/sources.html` (integration test now parametrized over both pages).
+- **Whole repo green:** 124 passed, `app/` coverage **99%**, ruff clean, pyright 0 errors; all 7 E2E suites pass.
+- **Screenshots** (1280/1440/375, both pages, in `.agent/screenshots/`) reviewed against PLAN §7.1–7.4 — pass.
+- **README:** quickstart verified against real scripts/flags; "Updating the documents" now prominent (intro callout + TL;DR one-liner, "workflow you'll use most" lead, Sources-page verification step).
+- Phase file moved to `.agent/phases/complete/`; 05/06 moves recorded in the commit too.
@@ -0,0 +1,34 @@
+
+-- 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/chat.py             84      0   100%
+app/api/docs.py             12      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               31      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               40      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         126      4    97%
+app/rag/importer.py        136      5    96%
+app/rag/llm.py              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py        49      0   100%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              32      0   100%
+--------------------------------------------
+TOTAL                      756     11    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,16 @@
+**Phase 08 — Dark Tech Theme: complete, all gates green, committed (`2f738a7`).**
+
+Implemented:
+- Dark token palette in `styles.css` (bg `#0a0e17`, surface `#121a2e`, brand `#6d78f2` with dark-ink text 5.2:1 — white-on-brand eliminated everywhere incl. skip-link, nav-active, user bubble, send button); radii 10/6px, black-based shadows, `::selection`, mono wordmark + stat values, 1px `--line` borders, 2px brand→cyan hairline under header; busy button keeps `#a5b4fc` with dark arc (9.7:1)
+- Emoji purge → inline SVG: favicon (504-byte hex+node data-URI), brand mark, banner triangle, empty-state glyphs (both pages); 🧠/🧑 avatars → SVG string constants in `app.js` (aria-hidden retained)
+- Pure-CSS animated background: `body::before` 44px grid (35% alpha, radial mask, 60s seamless drift) + `body::after` indigo/cyan glows (14s breathing), both `fixed`/`z-index:-1`/`pointer-events:none`; `prefers-reduced-motion` → `animation: none` (static layers remain)
+- Tests: new `tests/e2e/test_dark_tech_theme.py` (6 tests), new integration `test_ui_chrome_has_no_emoji` (4 paths), updated light-palette assertions in `test_honest_deflection.py` + `test_suggestion_chips.py`
+
+Verification (exact):
+- `uv run pytest tests/e2e/test_dark_tech_theme.py -v --no-cov` → 6 passed
+- `uv run pytest tests/e2e/test_chat_rag.py -v --no-cov` → 3 passed; `test_honest_deflection.py` → 3 passed; `test_responsive_polish.py` → 7 passed; smoke+suggestion_chips → 7 passed; import_documents+loading_feedback → 8 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → 128 passed, app/ 99% (>90%); `uv run ruff check .` clean; `uv run pyright` → 0 errors
+
+Decisions: dark bg lives on `<html>` (canvas) with `<body>` transparent — an opaque body would paint over the z-index:-1 layers (phase recipe); E2E asserts canvas bg `rgb(10, 14, 23)` + transparent body. Also updated the two chip-color assertions (brand-soft/brand-ink) the phase didn't list but the reskin would have broken. Owner's pending PLAN.md revisions recorded in the commit; README emoji left (not UI chrome).
+
+Next pending phase: `09_story_retrieval_quality.md`.
@@ -0,0 +1,34 @@
+
+-- 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/chat.py             84      0   100%
+app/api/docs.py             12      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               31      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               40      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         126      4    97%
+app/rag/importer.py        136      5    96%
+app/rag/llm.py              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py        49      0   100%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              32      0   100%
+--------------------------------------------
+TOTAL                      756     11    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,15 @@
+Phase 09 is complete. Final report:
+
+**Phase 09 report — commit `7e8d147`** (36 files, +2021/−293)
+
+- **A7 hybrid retrieval:** cosine top-100 ∪ Postgres FTS top-30 (stored `tsvector` + GIN, OR-tsquery), RRF k=60, LOCKED tiebreak. Fusion iteration = vector window 30→100: measured `gitlab.md:1` double-hit 0.02212 > template 0.01639 → **"How did I install gitlab?" now ranks gitlab.md #1** ✓
+- **A8 gate:** LOW only when best cosine < 0.62 **and** `fts_hits == 0`; `fts_hits` in per-turn log + `query_log` (migration 0002, nullable)
+- **A9 scope:** `md,markdown,txt,yaml,yml,json,py` (stdlib-only chunkers: YAML `---`/top-level keys, JSON top-level keys, `ast` defs/classes), dot-prefixed paths skipped, `--prune` drops filter-outs, per-format summary counts
+- **Live KB re-import:** 520 docs / 2774 chunks / 0 errors in 72s; **zero dot-prefixed paths**; k8s/backup/dns questions all ground correctly
+- **Gates:** 174 unit+integration passed · coverage 98% (>90%) · ruff + pyright clean · all 9 E2E suites green in isolation, incl. new `test_retrieval_quality.py` (4 tests: multi-format import, gitlab grounding, FTS-beats-vector, sourdough deflection)
+
+**Deviations (flagged per protocol, not silent):**
+- "sourdough → LOW" is **unmet at the locked 0.62**: measured off-topic best-cosine floor with the real `embed` model is **0.73** (battery: off 0.61–0.73, on 0.65–0.84 — the phase's 0.41–0.58 assumption was too low), so the gate answers. Fix when you want it: `BOR_RELEVANCE_THRESHOLD≈0.77` (then salsa/travel/sourdough deflect; common-word off-topic like tire/pizza still answers via the owner-approved FTS-OR).
+- `gitlab-compose.yaml` lands **#3, not top-2** (sits at vector rank 483; no sane window lets it outrank the template's double-free 1/61 term).
+
+Next pending: `10_story_document_viewer.md`.
@@ -0,0 +1,34 @@
+
+-- 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/chat.py             86      0   100%
+app/api/docs.py             12      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               49      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               41      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              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py       102      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              32      0   100%
+--------------------------------------------
+TOTAL                      924     14    98%
+coverage gate: app/ 98% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,18 @@
+Phase 10 complete — all gates green, committed as `6ec6181`.
+
+**Implemented**
+- `GET /api/documents/content?source=…&path=…` (`app/api/docs.py`, `DocContent` in `app/schemas.py`) — DB-only lookup, 404 `{detail:"document not found"}`, `format` from lowercased suffix (`text` fallback)
+- Extracted the escape-first markdown renderer to `frontend/assets/markdown.js` (classic script, relative `<script src>` on `index.html` + `document.html`); rendering unchanged
+- New dark-themed viewer page `frontend/document.html` + `document.js`: back link (history-aware), title, meta badges (source/format/mono path/indexed/chunks), md → ≤46rem rendered column, other formats → escaped `<pre class="doc-raw">`, designed 404 not-found card, landmarks/skip-link/`aria-live`/focus-to-main
+- Chat source chips + Sources-table path links → viewer in a new tab (`target="_blank" rel="noopener"`, percent-encoded URLs); no-CDN + emoji guards extended to the viewer; README UI section
+
+**Verification**
+- `uv run pytest --cov=app --cov-report=term-missing` → 201 passed, **99%** on `app/` (>90%)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+- `uv run pytest tests/e2e/test_document_viewer.py -v --no-cov` → 5 passed (isolated)
+- All 9 existing story E2E suites re-run in isolation → all pass (incl. XSS-proofing E2E: `<script>` fixture renders escaped, no dialog)
+
+**Notable**
+- E2E source values are `docs` (imported-dir basename) with slash-bearing paths — exactly what the query encoding handles; updated the now-stale chip-href assertion in the phase-03 suite (`/sources.html` → encoded viewer URL) and kept the cell-level `title` (phase-02 contract) alongside the link's.
+
+**Next pending phase:** none — `10_story_document_viewer.md` was the last in `todo/` (roadmap complete).
@@ -0,0 +1,34 @@
+
+-- 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/chat.py             86      0   100%
+app/api/docs.py             22      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               49      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               41      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              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py       102      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              40      0   100%
+--------------------------------------------
+TOTAL                      942     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,11 @@
+**Phase 12 — One Header, Same Size Everywhere: complete**
+
+- `.doc-header` fixed to `var(--header-h)` (64px desktop / 58px mobile), inner centered, meta row `nowrap` + clips (no wrap growth); `flex-wrap: nowrap` on the mobile inner rule.
+- Fixed a **pre-existing flex-shrink defect** (affects all pages): `body` is a definite-height flex column, so `.app-header`/`.doc-header` shrank to content-min (44px) on any page whose content overflows the viewport — this was a second cause of the owner's "header changes size" report (Sources at ≤640px). Added `flex-shrink: 0` to both headers.
+- `.doc-path` given `min-width: 6rem` so it stays the visible ellipsis target on narrow screens (flex would otherwise shrink it to 0px and clip the badges instead).
+- E2E: `tests/e2e/test_header_consistency.py` (3 tests: desktop 1280 / mobile 375 three-page box comparison + phase-10 content regression).
+- Results: `uv run pytest --cov=app --cov-report=term-missing` → 203 passed, **99%** coverage; `uv run ruff check .` → clean; `uv run pyright` → 0 errors; `uv run pytest tests/e2e/test_header_consistency.py -v --no-cov` → **3 passed** (isolation); `test_document_viewer.py` → 5 passed (isolation); remaining 10 E2E files → 40 passed.
+- Deviation: phase step 3 (PLAN §7.1 note) skipped — harness rules forbid editing `.agent/PLAN.md`; no other lock decisions touched.
+- Committed `8ca564c` (`--no-gpg-sign`), tree clean.
+
+**Next pending phase:** `.agent/phases/todo/13_document_back_navigation.md`
@@ -0,0 +1,34 @@
+
+-- 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/chat.py             86      0   100%
+app/api/docs.py             22      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               50      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               41      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              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py       102      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              40      0   100%
+--------------------------------------------
+TOTAL                      943     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,18 @@
+**Phase 13 complete** — committed as `2485b50`, tree clean.
+
+**Implemented**
+- Chat source chips carry `&back=%2F`: `documentUrl(source, path, back = "/")` in `frontend/assets/app.js` (percent-encoded).
+- Viewer (`frontend/assets/document.js`): back target resolved from the `back` param — honored only for same-origin relative URLs (starts with `/`, not `//`); `https://`, `//`, `javascript:` etc. fall back to `/sources.html`. Label set to Chat / Sources / Back. Dropped the `history.length` heuristic entirely — with `href` set, the anchor's default click IS the deterministic navigation; static `href="/sources.html"` no-JS fallback untouched.
+- Sources links unchanged (no `back` param → default `/sources.html`).
+- New E2E `tests/e2e/test_document_back_navigation.py` (3 tests per story mapping, incl. malicious-param rejection); updated stale contract pins: phase-10 E2E chip href, phase-03 `test_chat_rag.py` href, and phase-10 unit pins in `tests/unit/test_document_viewer.py` (re-pinned to the new builder/resolution contract, plus a node behavioral check for `back` encoding).
+
+**Verification (all green)**
+- `uv run pytest tests/e2e/test_document_back_navigation.py -v --no-cov` → 3 passed
+- `uv run pytest tests/e2e/test_document_viewer.py -v --no-cov` → 5 passed
+- `uv run pytest --cov=app --cov-report=term` → 203 passed, `app/` coverage **99%** (>90%)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+- Full E2E regression sweep (`uv run pytest tests/e2e --no-cov`) → 51 passed
+
+**Decisions**: removed the click listener rather than forcing `location.assign` (cleaner, same determinism); a pyright complaint in the new E2E was fixed by using the phase-10 named dialog-handler pattern.
+
+**Next pending phase**: `.agent/phases/todo/14_chat_persistence.md`
@@ -0,0 +1,34 @@
+
+-- 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/chat.py             86      0   100%
+app/api/docs.py             22      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               50      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               41      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              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py       102      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              40      0   100%
+--------------------------------------------
+TOTAL                      943     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+Working tree clean, phase committed. Final report:
+
+**Phase 14 — Chat persistence: complete**
+- `app.js`: conversation model + save/restore/clear on `bor.chat.v1` (raw text only, re-rendered through escape-first markdown; user saved on send, brain on `done` with sources/deflected/suggestions; 700k-char budget dropping oldest first; every localStorage access try/catch'd; failed turns keep the question)
+- `#new-chat-btn` ghost pill in chat header (icon-only ≤640px, aria-label, ≥44px), clears key + list, restores empty state, confirms via `#send-status` live region; ignored mid-turn
+- `index.html`/`styles.css`: button + Phase-08 tokens, header layout via `margin-left:auto` (Sources header unchanged)
+- Tests: new `tests/e2e/test_chat_persistence.py` (4 story-mapped tests) + `tests/unit/test_chat_persistence.py` (8 contract pins incl. structural try/catch check)
+
+**Results**
+- `uv run pytest tests/unit tests/integration` → 211 passed
+- `uv run pytest --cov=app` → **99%** (gate >90%)
+- `uv run ruff check .` + `uv run pyright` → clean, 0 errors
+- Story E2E `tests/e2e/test_chat_persistence.py -v --no-cov` → 4 passed; all 15 E2E suites green in isolation (incl. regressions: chat_rag 3, suggestion_chips 4, loading_feedback 5, header_consistency 3, responsive_polish 7 — no 360px overflow)
+- Commit `19df7df` (`--no-gpg-sign`)
+
+**Deviations:** phase step 4 asks for PLAN §7.5/§7.4 notes, but harness rules forbid editing `.agent/PLAN.md` — left for the harness.
+**Next pending phase:** `15_steering_notes.md`
@@ -0,0 +1,34 @@
+
+-- 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/chat.py             86      0   100%
+app/api/docs.py             22      0   100%
+app/api/health.py           10      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               50      0   100%
+app/core/__init__.py         0      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                 28      0   100%
+app/models.py               41      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              94      0   100%
+app/rag/prompts.py          15      0   100%
+app/rag/retriever.py       102      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              40      0   100%
+--------------------------------------------
+TOTAL                      943     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,22 @@
+Phase 15 complete. Final report:
+
+**Implemented**
+- `steering_notes` table (migration 0003, applied) + `SteeringNote` model + `BOR_STEERING_MAX_CHARS` setting
+- Stateless CRUD: `GET/POST /api/steering` (trimmed, 1–2000 chars, 201/422), `DELETE /api/steering/{id}` (204/404), newest-first list
+- `<tuning>` prompt section (numbered, budget-capped with `[…truncated…]`) in **both** HIGH and DEFLECT prompts, between `<relevance>` and the mode body; zero-note prompts byte-identical to before; per-turn log gains `tuning=N`
+- E2E mock echoes first tuning note as ` (tuning: …)` suffix
+- UI: Tune button in every completed brain bubble's meta row (≥44px), inline labeled form (maxlength 2000, keep-on-failure error `role=alert`, `.tune-saved` `role=status`), header "Tuning" toggle + count badge + panel (region, newest-first, labeled per-note delete, polite live-region announcer), text-only note rendering (XSS-safe), Phase-08 tokens
+- README "Tuning your answers" + config rows; owner's persona edits applied (no "you've got this", no mandated deflection opening) with verbatim test aligned
+
+**Gates**
+- `uv run pytest --cov=app --cov-report=term-missing` → 241 passed, **99%** (was 98.9% pre-phase)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+- `uv run pytest tests/e2e/test_steering.py -v --no-cov` → 4 passed; regressions `test_chat_rag`/`test_honest_deflection`/`test_retrieval_quality` + all 13 other E2E suites green in isolation
+- Committed: `fc0d9a2 feat(rag): steering notes — tune how Brain answers…` (`--no-gpg-sign`)
+
+**Decisions/deviations**
+- `.agent/PLAN.md` untouched (harness rule overrides phase step 7) — the PLAN §6 persona revision is recorded in `app/rag/prompts.py` + test docstrings instead; §4/§5/§7.5/§9/roadmap rows still need the harness/owner update
+- Owner's persona edits weren't present in the (clean) working tree; I applied exactly the two documented edits
+- Unit file named `test_steering_prompts.py` (basename collision with integration `test_steering.py`); killed a stale pre-change uvicorn squatting on port 8123 that initially masked E2E results
+
+**Next pending phase:** none — `todo/` is empty.
@@ -0,0 +1,34 @@
+-- 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/chat.py             90      0   100%
+app/api/docs.py             22      0   100%
+app/api/health.py           10      0   100%
+app/api/steering.py         32      0   100%
+app/api/suggestions.py       8      0   100%
+app/config.py               51      0   100%
+app/core/__init__.py         0      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                 30      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              94      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              54      0   100%
+--------------------------------------------
+TOTAL                     1030     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,14 @@
+All green and committed. Final report:
+
+**Phase 16 (Admin Sign-In) — complete**
+
+- **Verified pre-existing work:** backend (fail-loud config, `core/auth.py`, `/api/login|logout|whoami`, `require_admin` on `/api/docs` + `/api/steering`, SessionMiddleware) and frontend (login page, chat auth gating incl. restore path, `#sources-gate`) + unit/integration/E2E tests were in tree but uncommitted/unverified.
+- **Implemented the gaps:** `.env.example` auth section; README "Admin & sign-in" (setup one-liner, fail-loud, anon-vs-admin table, config rows); task-11 regression adaptations — `test_steering`, `test_import_documents`, `test_document_back_navigation` (form login via `auth_helpers`), `test_header_consistency` (auth-link presence in both states, heights unchanged).
+- **Fixed previously-completed suites broken by the new gating:** `test_chat_persistence`, `test_document_viewer`, `test_dark_tech_theme`, `test_responsive_polish`, `test_retrieval_quality` (login + signed-cookie httpx).
+- **Kept `itsdangerous` direct dep** (starlette 1.6 made it an optional `full` extra — without it `SessionMiddleware` import crashes); added explanatory pyproject comment.
+- Tests: `uv run pytest --cov=app` → **270 passed, 99% coverage** (>90%); `uv run ruff check .` clean; `uv run pyright` 0 errors.
+- E2E in isolation: `test_admin_auth.py` **6/6**; regressions green — steering 4, import 3, back-nav 2, header 3, chat_rag 5, viewer 7; plus chat_persistence 4, dark_theme 6, responsive 7, retrieval 4, smoke 3, chips 4, loading 5, deflection 3, long 2.
+- Startup criteria: no env → `RuntimeError` naming `BOR_ADMIN_PASSWORD, BOR_SESSION_SECRET` (exit 1); set → serves (health 200, anon `/api/docs` 403, login 204+cookie, admin 200, whoami admin). Login page UI check: landmarks, labeled input, ≥44px, focus-visible 3px, role=alert, AA tokens, no CDN — all verified.
+- Commit `cbc263a` (`--no-gpg-sign`, exact phase message; included pyproject/uv.lock); phase file left in `todo/` for the harness.
+- **Deviations:** PLAN.md revisions from task 9 **not applied** (executor rule forbids editing `.agent/PLAN.md` — needs harness/owner follow-up); itsdangerous dep as above.
+- **Next pending phase:** none — 16 is the last in `todo/`.
@@ -0,0 +1,34 @@
+_______________ 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             90      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              94      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              59      0   100%
+--------------------------------------------
+TOTAL                     1089     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,13 @@
+Verification complete — all green. Final report:
+
+**Phase 17 — final verification pass (all tasks already in `complete/`, commit `b16deb2` present)**
+
+- **Verified, no code changes needed:** StreamPiece→SSE `thinking` plumbing (llm.py/chat.py/schemas/config), collapsible `.thinking` block (streaming open, auto-collapse, user-toggle, persisted collapsed, stream-drop guard), mock trigger + story suite, docs (user story, PLAN §2/§4/§7.4/§7.5/§9/§12 all carry the 2026-08-23 owner-permission notes, `.env.example` `BOR_STREAM_THINKING`)
+- `uv run pytest --cov=app --cov-report=term-missing` → **288 passed, 99% coverage** (>90%)
+- `uv run pytest tests/e2e/test_thinking_display.py -v --no-cov` → **5/5 passed** in isolation
+- Regression suites in isolation: `test_chat_rag` 3 ✓, `test_loading_feedback` 5 ✓, `test_chat_persistence` 4 ✓, `test_honest_deflection` 3 ✓
+- `uv run ruff check . && uv run pyright` → **clean** (0 errors)
+- **Live check (real aipi, dev server):** thinking frames stream before all deltas, `done` shape unchanged, log line shows `thinking_chars=5317` before `total_ms`; with `BOR_STREAM_THINKING=0` → 0 thinking frames, deltas/`done` identical, chars still counted
+- **UI Structure Check:** Phase-08 tokens, contrast 8.7:1/6.9:1, 44px summary target, focus-visible, chevron gated by `prefers-reduced-motion`, no CDN tags, 46rem column intact
+- Only anomaly seen was transient — my own parallel pytest runs sharing one Postgres caused 1 error + 1 E2E failure; both green on sequential re-run (not a code defect)
+- Next pending phase: **`18_follow_bottom_scroll`** (then `19_shared_header`)
@@ -0,0 +1,34 @@
+_______________ 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,19 @@
+Task 01 complete — all gates green.
+
+**Implemented**
+- `app/rag/llm.py`: frozen `StreamPiece(kind, text)`; `chat_stream` now yields `AsyncIterator[StreamPiece]` — `delta.reasoning_content` (verified wire field) → thinking piece with `delta.reasoning` fallback, thinking before content per chunk; `LLMError` wrap + gen params unchanged; docstrings updated
+- `app/schemas.py`: `ChatThinkingEvent` (`{type:"thinking", text}`)
+- `app/config.py`: `stream_thinking: bool = True` (`BOR_STREAM_THINKING` kill-switch)
+- `app/api/chat.py`: pieces → `thinking`/`delta` SSE events; `thinking_chars` counted always, emitted only when enabled; `thinking_chars=N` inserted before `total_ms=N` in the per-turn log line
+- `.env.example`: `BOR_STREAM_THINKING=1`; tests extended (llm client ×4 new, SSE frame, config, integration ×2); adapted pre-existing string-yielding fakes (`test_chat_gate.py`)
+
+**Results**
+- `uv run pytest tests/unit/test_llm_client.py tests/unit/test_sse_events.py tests/unit/test_config.py tests/integration/test_chat_api.py -v --no-cov` → 55 passed
+- `uv run pytest --cov=app --cov-report=term` → 279 passed, **99% coverage** (>90%)
+- `uv run ruff check . && uv run pyright` → clean, 0 errors
+- Live curl vs real aipi: 1360 `thinking` frames precede all 170 `delta` frames, `done` last, log line carries `thinking_chars=5612`; with `BOR_STREAM_THINKING=0` zero thinking frames, deltas intact, still counted (`thinking_chars=7187`)
+- Frontend untouched; its `readSSE` branches only on `delta`/`done`/`error`, so unknown `thinking` frames are ignored (no regression)
+
+**Deviations**: none. No commit made — the atomic commit belongs to task 04 per the phase plan.
+
+**Next pending task**: `.agent/phases/todo/17_thinking_display/02_frontend_thinking_block.md`
@@ -0,0 +1,34 @@
+_______________ 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,9 @@
+**Task 02 complete — frontend collapsible Thinking block.**
+
+- `app.js`: `thinking` SSE branch (accumulate → clear 120s guard → create wrap without state change → remove typing dots → stream escape-first markdown into the block, bottom-pinned while open); `ensureThinkingBlock`/`closeThinkingBlock` helpers; delta branch now transitions `thinking → streaming` and auto-collapses (never reopens); `done` sets `sawDone`, closes the block, renders + persists the shared `EMPTY_ANSWER_FALLBACK` on thinking-without-answer, and persists `thinking: thinkingAcc || undefined` (key dropped when absent — no version bump); `sawDone` stream-drop guard after `readSSE`; restore renders a collapsed block; header docs extended.
+- `styles.css`: `details.thinking`/`summary`/`.thinking-text` in Phase-08 tokens (44px target, 8.7:1 / 6.9:1, CSS chevron), chevron transition stills under `prefers-reduced-motion`.
+- Unit pins added in `test_frontend_feedback.py` (+6) and `test_chat_persistence.py` (+3); one stale pin (`rememberBrainTurn(acc` → `rememberBrainTurn(finalText || acc`) updated per the task's mandated call-site change.
+- `uv run pytest tests/unit/test_frontend_feedback.py tests/unit/test_chat_persistence.py -v --no-cov` → 23 passed; `uv run pytest` → 288 passed; `uv run pytest --cov=app` → 99% (>90%, unchanged from baseline); `uv run ruff check . && uv run pyright` → clean.
+- Browser-verified with a throwaway 5-scenario Playwright run (live app + thinking-capable mock, deleted after): streams open → collapses on first answer token, toggle works, reload restores collapsed block with same text, no-trigger turn renders with no block and no `thinking` key stored, deflection coexists. E2E regressions green in isolation: `test_chat_rag` (3), `test_loading_feedback` (5), `test_chat_persistence` (4), `test_honest_deflection` (3).
+- Note: the stream-drop guard is unit-pinned only — a clean early LLM-stream end is client-invisible (the app always emits `done` from its own generator); task 03's 5 scenarios don't E2E-cover it either.
+- Next pending task: `.agent/phases/todo/17_thinking_display/03_e2e_mock_and_story_suite.md` (mock `think out loud` trigger + `test_thinking_display.py`).
@@ -0,0 +1,34 @@
+_______________ 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,17 @@
+All gates green and the repository is left functional. Final report:
+
+**Task 03 (E2E mock + story suite) — complete**
+
+Implemented:
+- `tests/e2e/mock_llm.py`: `THINKING_TRIGGER = "think out loud"`, `compose_thinking()` (809-char deterministic 4-step scratchpad quoting the question, includes `Step 2: Check my notes`), `_sse_stream(answer, delay, thinking="")` (12-char `reasoning_content` frames at same 0.02s cadence before content frames; byte-identical without trigger), non-streaming `reasoning_content` future-proofing, docstring trigger bullet
+- `tests/e2e/test_thinking_display.py` (new, mock-only header note + determinism note): `seeded_kb` fixture (8-doc seed, truncate teardown, conftest `db_ready` skip) + `send_and_wait` helper + all 5 scenarios: stream open→auto-collapse, post-done toggle (keyboard-focusable summary), reload restore (closed block, matching text, raw-persisted check), no-block-without-trigger, thinking+deflection coexistence
+
+Results:
+- `uv run pytest tests/e2e/test_thinking_display.py -v --no-cov` → 5/5 passed (in isolation)
+- Regression, each in isolation: `test_chat_rag.py` 3 passed, `test_loading_feedback.py` 5 passed, `test_chat_persistence.py` 4 passed, `test_honest_deflection.py` 3 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → 288 passed, app coverage 99% (>90%)
+- `uv run ruff check . && uv run pyright` → clean (fixed a generator-fixture `Iterator[None]` annotation)
+
+Decisions: trigger substring verified collision-free (only "cloud-init" contains "loud"); no app/frontend bugs found — one fix was to my own test's whitespace-normalization assertion (renderMarkdown `<br>` drops newlines in textContent).
+
+Next pending task: `.agent/phases/todo/17_thinking_display/04_story_docs_plan_commit.md`
@@ -0,0 +1,34 @@
+_______________ 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,20 @@
+Task 04 complete. Final report:
+
+**Implemented**
+- `.agent/user_stories/thinking-display.md` — all five sections (header, narrative, 7 acceptance criteria, UI visualization & structure, Playwright Mapping Rule with the 5 task-03 scenarios verbatim)
+- README: new "Thinking" section after "Using the UI" (what it is, model's call, `BOR_STREAM_THINKING=0` kill-switch); `.env.example` line 19 verified present
+- `.agent/PLAN.md` revisions, all noting owner permission 2026-08-23: header revisions line, §4 `thinking` SSE frames + client rules + revision note, §7.4 "Thinking (model reasoning)" row + note, §7.5 `.thinking`/`.thinking-text`, §9 `thinking_chars=` in the per-turn log line, §12 roadmap row 17; no anchor text altered, nothing renumbered
+- One atomic commit: `b16deb2 feat(chat): stream model thinking over SSE and show it in a collapsible block` (18 files, `--no-gpg-sign`)
+
+**Gates (all green)**
+- `uv run pytest --cov=app --cov-report=term-missing` → 288 passed, 99% on `app/` (>90%)
+- `uv run pytest tests/e2e/test_thinking_display.py -v --no-cov` → 5/5 in isolation
+- Regressions in isolation: `test_chat_rag` 3/3, `test_loading_feedback` 5/5, `test_chat_persistence` 4/4, `test_honest_deflection` 3/3
+- `uv run ruff check . && uv run pyright` → clean; no CDN tags (block is dynamic JS, index template untouched)
+- Live aipi check: 1580 `thinking` frames before 267 `delta` frames, log line `thinking_chars=5581`; with `BOR_STREAM_THINKING=0` → 0 thinking frames, deltas unchanged, `thinking_chars=5011` still counted
+
+**Decisions / deviations**
+- Skipped the task's `mv …/17_thinking_display → complete/` — the harness protocol explicitly moves task files on success; left phase files in place
+- Commit staged the tracked `.agent/PLAN.md` + code/docs; gitignored phase/story files stay untracked (matches repo convention since phase 11; the task's `git add -A .agent/` resolves to exactly that)
+
+**Next pending task:** `18_follow_bottom_scroll` (after the harness moves task 04 to complete/).
@@ -0,0 +1,34 @@
+_______________ 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,10 @@
+**Task 01 complete — follow-the-bottom scroll gate in `app.js`**
+
+- `frontend/assets/app.js`: added exported `NEAR_BOTTOM_PX = 200`, `isNearBottom()` (document scroller), and `scrollReveal()` — now the **single** `scrollIntoView` call site (pinned to bottom OR forced). Rewired all call sites: `addMessage` (behavior/force passthrough), `addTyping`, the phase-17 `thinking` branch (keeps its internal `.thinking-text` pin), the `delta` branch, and both phase-14 restore call sites → `("auto", true)`. Submit stays the plain gated default. Header doc gained the "Scroll (phase 18)" paragraph.
+- **Defect found & fixed:** turn-end `input.focus()` (phase 06) scrolled the off-screen composer into view, yanking a top-scrolled user to the bottom the moment a turn ended — replaced with `input.focus({ preventScroll: true })` (verified via instrumented headless-browser timeline: 9.3s stream held scrollY=0 with it; yanked to 3871px without).
+- Updated the stale phase-14 unit pin (`tests/unit/test_chat_persistence.py`) to the forced restore form.
+- New `tests/unit/test_frontend_scroll.py`: 7 source-level pins (6 spec'd + 1 for the preventScroll fix).
+- Results: `uv run pytest` → **295 passed** · `uv run pytest --cov=app --cov-report=term-missing` → **99% (1109 stmts, 14 missed — identical to baseline)** · `uv run pytest tests/unit/test_frontend_scroll.py -v --no-cov` → 7 passed · `uv run ruff check . && uv run pyright` → clean (0 errors) · `rg -c "scrollIntoView" frontend/assets/app.js` → **1**.
+- Browser smoke (mock LLM + Chromium): pinned follow (max 64px from bottom ≤ 200), top-hold through a full delta stream, top-hold through thinking+answer, reload landing on the latest message — all pass. E2E regression sanity: `test_chat_persistence.py` 4/4, `test_thinking_display.py` 5/5.
+- No `index.html`/`styles.css`/template changes; no commit (single phase commit belongs to task 03).
+- Next pending task: `02_e2e_story_suite.md` (phase 18).
@@ -0,0 +1,34 @@
+_______________ 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,11 @@
+All green. The remaining working-tree diffs are phase 18 task 01's (already complete; task 03 owns the commit).
+
+**Task 02 report — `18_follow_bottom_scroll/02_e2e_story_suite.md`**
+
+- Implemented `tests/e2e/test_follow_bottom_scroll.py`: 5 Playwright scenarios (submit reveals message; follow alive while pinned; no-yank mid-answer with `scrollTo(0,0)` held ≤5px; no-yank during phase-17 thinking stream — full scratchpad + long answer land off-screen; restore still force-lands on the latest message), document-scroller measurement convention (`{y, sh, ch}` via `page.evaluate`, 200px band mirroring `NEAR_BOTTOM_PX`), `seeded_kb` fixture reusing conftest `db_ready`.
+- No `app/`, mock, or `frontend/` changes (no defects found — the suite passed against task 01's `scrollReveal` gate as-is).
+- `uv run pytest tests/e2e/test_follow_bottom_scroll.py -v --no-cov` → **5 passed** (114s, isolation).
+- Regressions, each in isolation: `test_thinking_display.py` 5 passed · `test_chat_persistence.py` 4 passed · `test_loading_feedback.py` 5 passed · `test_chat_rag.py` 3 passed · `test_suggestion_chips.py` 4 passed.
+- `uv run pytest` → 295 passed; `uv run pytest --cov=app --cov-report=term-missing` → **99%** (unchanged, >90% gate); `uv run ruff check . && uv run pyright` → clean (0 errors).
+- Notable: mock-only suite (`E2E_REAL_LLM=1` unsupported — scroll-away windows need deterministic pacing); one f-string brace-escape fix during authoring.
+- Next pending task: `03_docs_plan_commit.md` (user story file, PLAN revisions, final validation, the atomic `--no-gpg-sign` commit, phase move).
@@ -0,0 +1,34 @@
+_______________ 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,11 @@
+All green (pytest exit 0; summary matches the earlier full run of 295 passed). Phase 18 is complete.
+
+**Task 03 report — `18_follow_bottom_scroll` (docs, PLAN, validation, commit)**
+
+- Created `.agent/user_stories/follow-bottom-scroll.md` (header, narrative, 6 acceptance criteria, UI visualization, verbatim 5-scenario Playwright Mapping Rule — matches sibling format)
+- `.agent/PLAN.md`: header revisions line + §7.4 "Scroll (follow-the-bottom, phase 18)" row + §12 row 18, each noting the owner choice (2026-08-23, option 1 — no pill); no anchor text altered; README untouched (per task)
+- Gates: `uv run pytest --cov=app --cov-report=term-missing` → 295 passed, **99%** coverage; `uv run pytest tests/e2e/test_follow_bottom_scroll.py -v --no-cov` → 5/5 in isolation; regressions in isolation: thinking_display 5✓, chat_persistence 4✓, loading_feedback 5✓, chat_rag 3✓, suggestion_chips 4✓; `uv run ruff check . && uv run pyright` clean; `rg -c "scrollIntoView" frontend/assets/app.js` → 1
+- Commit `bc0158f` `feat(ui): chat auto-scrolls only while pinned to the bottom — …` (conventional, `--no-gpg-sign`); phase dir now under `.agent/phases/complete/`
+- Deviations: (1) task's `git add -A .agent/` errors on the ignored pathspec in this git — staged via `git add -f .agent/PLAN.md` (the AGENTS.md rule-8 mechanism); (2) `mv` of the todo dir failed because the harness had already moved tasks 01/02 into `complete/18` — merged remaining `00`/`03` files in and removed the todo dir; (3) header line carries "(Phase 18, owner choice 2026-08-23)" so the owner-choice wording sits on every note, per the phase-17 precedent
+
+Next pending task: `.agent/phases/todo/19_shared_header/` (first task in that phase).
@@ -0,0 +1,34 @@
+_______________ 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,18 @@
+All gates green. Task 01 complete.
+
+**Implemented**
+- `frontend/assets/header.js` (new): `fetchIsAdmin` (module-level cached `adminPromise` — one whoami/page), `initSharedHeader` (null-safe toggles of `#sign-in-link`/`#sign-out-btn`/`#nav-sources`, returns admin flag), `clearChatStorage` (`bor.chat.v1`, try/catch), module-owned `#sign-out-btn` binding (disable → POST `/api/logout` → reload)
+- Wiring: `#nav-sources` (ships `hidden`) on index/sources/login; New Chat + Sign in/out (both `hidden`) on sources + viewer (`.doc-header-actions`, `next=` per page); `header.js` loads before each page script; login page control-free
+- `app.js` (imports shared module, boot = `initSharedHeader()` → `fetchIsAdmin()` → `applyAuthState()`, `loadAuthState` + sign-out listener deleted), `sources.js`/`document.js` (New Chat → clear storage → `/`), `login.js` (shared `fetchIsAdmin`, redirect unchanged)
+- `styles.css`: `.doc-header-actions` (title block `min-width:0` already existed)
+- `tests/unit/test_shared_header.py` (14 pins); adapted the superseded phase-14 pin `test_new_chat_button_in_chat_header_only` → shared-bar contract (its "nowhere else" assertion was deliberately overturned by this phase)
+
+**Verification**
+- `uv run pytest tests/unit/test_shared_header.py -v --no-cov` → 14 passed
+- `uv run pytest` → 309 passed; `uv run pytest --cov=app` → 99% (baseline 99%, `app/` untouched)
+- `uv run ruff check .` clean; `uv run pyright` → 0 errors
+- Browser sanity (mock LLM + real app, 55/55 checks): anon/admin bars on all 4 pages, exactly one whoami/load, New Chat from sources clears `bor.chat.v1` → empty state, sign-out from viewer, 64/58px held, no 360px overflow; dev DB restored to empty
+
+**Decisions**: E2E regression adaptations (incl. `tests/e2e/test_chat_persistence.py`'s `#new-chat-btn` count assertion) left to task 02 per its scope; PLAN/story/commit are task 03.
+
+**Next pending task**: `.agent/phases/todo/19_shared_header/02_e2e_story_suite.md`
@@ -0,0 +1 @@
+bash: .agent/validate.sh: No such file or directory
@@ -0,0 +1,14 @@
+**Fixed this attempt**
+- Recreated the missing `.agent/validate.sh` (the harness's per-task gate) — the project-adapted version matching prior successful phases' output: `uv run pytest --cov=app --cov-report=term` + coverage floor check → "coverage gate: app/ NN% (>90%) OK" → `uv run ruff check .` → `uv run pyright` → "validation OK"; verified its failure path (89% correctly fails, 91% passes)
+- All task-01 frontend work from the previous attempt was intact and re-verified (no code changes needed)
+
+**Verification**
+- `bash .agent/validate.sh` → exit 0, ends "coverage gate: app/ 99% (>90%) OK / All checks passed! / 0 errors, 0 warnings, 0 informations / validation OK"
+- `uv run pytest tests/unit/test_shared_header.py -v --no-cov` → 14 passed
+- `uv run pytest` (unit + integration) → 309 passed
+- `uv run ruff check .` clean; `uv run pyright` 0 errors; coverage 99% (baseline held, `app/` untouched)
+- Browser sanity (prior run, 55/55 checks): anon/admin bars on chat/sources/viewer/login, one whoami per load, New Chat from sources clears `bor.chat.v1` → empty state, sign-out from viewer, 64/58px held, no 360px overflow
+
+**Decisions**: validate.sh is the project-adapted template (generic skill template would miss the uv/coverage/pyright gates); E2E regression adaptations remain task 02's scope; PLAN/story/commit are task 03.
+
+**Next pending task**: `.agent/phases/todo/19_shared_header/02_e2e_story_suite.md`
@@ -0,0 +1,46 @@
+........................................................................ [ 23%]
+........................................................................ [ 46%]
+........................................................................ [ 69%]
+........................................................................ [ 93%]
+.....................                                                    [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,17 @@
+Task 02 complete — all gates green.
+
+**Implemented**
+- `tests/e2e/test_shared_header.py` (new, 6 scenarios): shared-bar contract helper `assert_shared_bar(admin, page_kind)` (settled-state waits, one auth control, New Chat everywhere, `#nav-sources` admin-only on chat/sources / absent in viewer, 64/58px bounding-box heights) + the six story scenarios (anonymous bar ×3, admin bar ×3 via `login(next="/")`, nav-link hidden on chat/sources/login + toggle after login, New Chat from sources clears `bor.chat.v1` and lands on the empty state, sign out from the viewer, 375px mobile heights + overflow in both auth states)
+- Adapted `tests/e2e/test_chat_persistence.py` test 4: its stale "New chat is chat-page-only" assertion (phase-14 contract) contradicts the owner-confirmed phase-19 shared bar — now asserts the button is visible on sources, with a phase-19 note (phase-12→16 regression-adaptation precedent)
+
+**Results** (all in isolation, DB up)
+- `uv run pytest tests/e2e/test_shared_header.py -v --no-cov` → 6/6 passed
+- Regressions: `test_header_consistency.py` 3 passed · `test_responsive_polish.py` 7 passed · `test_admin_auth.py` 6 passed · `test_document_back_navigation.py` 3 passed · `test_chat_persistence.py` 4 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → 309 passed, 99% app coverage (gate >90%)
+- `uv run ruff check . && uv run pyright` → clean (0 errors)
+
+**Decisions**
+- Storage seed for scenario 4 uses an IIFE init script scoped to `/sources.html` (init scripts run on every navigation — unscoped re-seeding would defeat the "key removed" assertion)
+- No `app/`, no frontend, no `.agent/` changes needed — task 01's implementation passed the whole suite as-is
+
+**Next pending task:** `.agent/phases/todo/19_shared_header/03_docs_plan_commit.md`
@@ -0,0 +1,46 @@
+........................................................................ [ 23%]
+........................................................................ [ 46%]
+........................................................................ [ 69%]
+........................................................................ [ 93%]
+.....................                                                    [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,19 @@
+Task 03 complete — all gates green, phase committed and moved.
+
+**Implemented**
+- `.agent/PLAN.md` restored (it had been removed from the tree by the "uncommit .agent" commit) from last committed state `bc0158f`, then revised per task: header-revisions line (+`shared header (Phase 19)`), §2 A10 revision note (phase-16 2026-08-22 text recorded — it had **never** been applied per phase-16's deviation report — with the 2026-08-23 UI-revision note appended verbatim; A10 table row verified byte-identical), §7.1 shared-header contract, §7.5 new ids (+ unrecorded phase-16 ids), §12 roadmap row 19 + note
+- `.agent/user_stories/shared-header.md` created (all five sections; six scenarios verbatim from task 02)
+- README untouched (no operator-facing change); owner's untracked `TODO.md` left alone
+
+**Gates** (all re-run this session, after file work)
+- `uv run pytest --cov=app --cov-report=term-missing` → 309 passed, **99%** app coverage (baseline held)
+- `uv run pytest tests/e2e/test_shared_header.py -v --no-cov` → **6/6** in isolation
+- Regressions, one command each in isolation: header_consistency 3, responsive_polish 7, admin_auth 6, document_back_navigation 3, chat_persistence 4 — all passed
+- `uv run ruff check . && uv run pyright` → clean (0 errors)
+
+**Decisions/deviations**
+- Story says both auth controls ship hidden (phase-16 pattern, whoami reveals exactly one) — actual code, not the task's "sign-in visible-by-default" wording
+- Commit `2afc77e` stages only `frontend/` + `tests/`: `.agent/` is gitignored and the owner's latest action (076358d) uncommitted it, so no `-f` force-add
+- Phase dir merged into the pre-existing `complete/19_shared_header/` (tasks 01–02 already there); `todo/` now empty
+
+**Next pending task:** none — `19_shared_header` was the last phase in `todo/`.
@@ -0,0 +1,46 @@
+........................................................................ [ 23%]
+........................................................................ [ 46%]
+........................................................................ [ 69%]
+........................................................................ [ 93%]
+.....................                                                    [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 @@
+All verification complete. Every criterion checks out — this was a verification pass (both tasks already done and committed).
+
+**Phase 20 — Sources Mid-Stream: final verification pass — all green**
+
+- Verified `app.js` `pagehide` handler: in-flight guard (`thinking`/`streaming` + non-empty `acc`), reuses `rememberBrainTurn(acc, { thinking: thinkingAcc || undefined })`, turn-scoped idempotency flag `persistedOnLeave` (module-scope hoist of `acc`/`thinkingAcc`, reset per turn in `handleSend`); persistence comment lists the 3rd save point; `clearChatStorage` untouched
+- Tests/lint/coverage: `uv run pytest --cov=app --cov-report=term-missing` → **315 passed, 99% app coverage** (≥90% gate, unchanged — frontend-only); `uv run ruff check . && uv run pyright` → clean (0 errors)
+- E2E story suite (isolated, db up): `uv run pytest tests/e2e/test_sources_midstream_bug.py -v --no-cov` → **4/4 passed** (8.5s)
+- Regressions (isolated): `test_chat_persistence.py` 4/4, `test_thinking_display.py` 5/5, `test_shared_header.py` 6/6 — all green
+- Criteria: mid-stream Sources nav → question + partial rendered, no alert, `bor.chat.v1` holds partial ✅ · pre-token nav → question only, zero brain bubbles ✅ · completed turn sources/deflection/suggestions intact ✅ · New Chat from sources clears ✅ · story file `.agent/user_stories/sources-midstream.md` exists ✅
+- UI Structure Check ✅ — no new surface; partial renders through existing bubble/thinking contract (app.js logic-only diff)
+- Commit ✅ — `76c6a01` "fix(chat): keep the in-flight answer when navigating away mid-turn" (`--no-gpg-sign`); tasks 01/02 in `complete/`; `00_phase.md` left in `todo/` for the harness to move
+- Deviations: none. Pending tree entry `D …/todo/20_sources_midstream_bug/02_…md` is the harness's task-file move (tracked-file deletion), untouched per protocol
+- Next pending phase: `21_thinking_no_scroll`
@@ -0,0 +1,46 @@
+........................................................................ [ 22%]
+........................................................................ [ 45%]
+........................................................................ [ 68%]
+........................................................................ [ 91%]
+...........................                                              [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,17 @@
+Task 01 complete. Report:
+
+**Implemented**
+- `frontend/assets/app.js`: one new `pagehide` save point — in-flight guard (`uiState` = thinking/streaming) + non-empty `acc`, persists the partial via the existing `rememberBrainTurn(acc, { thinking: thinkingAcc || undefined })`; turn-local `persistedOnLeave` idempotency flag (module-scope hoist of `acc`/`thinkingAcc`, reset per turn at the top of `handleSend`, zero behavior change)
+- Persistence block comment now lists all three save points (send / done / navigate-away)
+- New `tests/unit/test_sources_midstream.py` — 6 source-level pins (single listener, guard order, helper reuse with no duplicated storage code, flag scoping/reset, comment, `clearChatStorage` still the only deliberate literal-key clear)
+
+**Results**
+- `uv run pytest tests/unit/test_sources_midstream.py -v` → 6 passed
+- `uv run pytest` → 315 passed (existing persistence pins untouched and green)
+- `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 99% (gate >90%, unchanged — frontend-only)
+- `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors; `node --check` on app.js → syntax OK
+
+**Decisions**
+- Task file names the turn function `runTurn`; the actual one is `handleSend` — pinned against the real name (task allows matching names actually in scope). No commit made — the atomic commit + phase move belong to task 02.
+
+**Next pending task:** `02_e2e_story_suite_commit.md` (E2E suite, regressions, story file, commit, phase move)
@@ -0,0 +1,46 @@
+........................................................................ [ 22%]
+........................................................................ [ 45%]
+........................................................................ [ 68%]
+........................................................................ [ 91%]
+...........................                                              [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,11 @@
+All green. Final state verified — report:
+
+**Phase 20 task 02 complete — all gates green**
+- Implemented: `tests/e2e/test_sources_midstream_bug.py` (4 scenarios: mid-stream Sources-nav restores partial answer; pure-thinking nav persists nothing brain-side; completed turn byte-identical; sources-page New Chat still clears) + additive mock trigger `think out loud then hesitate` (4s pre-content pause; byte-identical for all other suites) + `.agent/user_stories/sources-midstream.md`
+- `uv run pytest tests/e2e/test_sources_midstream_bug.py -v --no-cov` → 4/4 in isolation
+- Regressions, isolated: `test_chat_persistence.py` 4/4 · `test_thinking_display.py` 5/5 · `test_shared_header.py` 6/6 (extra safety: long_answers+loading_feedback+honest_deflection 10/10)
+- `uv run pytest --cov=app --cov-report=term-missing` → 315 passed, **99%** (baseline held, no `app/` changes); `uv run ruff check . && uv run pyright` → clean, 0 errors
+- UI Structure Check: no new surface/ids — partial restores through the existing bubble/thinking contract (pinned in E2E: no thinking block, no chips, no `role=alert`)
+- Commit `76c6a01` (task's exact message, `--no-gpg-sign`, 5 files): app.js pagehide save point (task 01) + unit pins + mock + E2E + story-file deletion record
+- Deviations: literal `git add -A .agent/` is git-rejected (ignored path) — equivalent staging done; new `.agent` plan files stay untracked/ignored per post-`076358d` repo precedent; phase-dir move left to the harness (task 01 was already harness-moved); E2E scenario 1 doubles as task 01's browser-level smoke
+- Next pending task: `.agent/phases/todo/21_thinking_no_scroll/01_disable_thinking_scroll.md`
@@ -0,0 +1,46 @@
+........................................................................ [ 22%]
+........................................................................ [ 45%]
+........................................................................ [ 68%]
+........................................................................ [ 91%]
+...........................                                              [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,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: `.agent/user_stories/thinking-no-scroll.md`
+- Phase report: `.agent/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 `.agent/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: `.agent/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
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`(no final assistant message — see the .err log)`
				`@@ -0,0 +1 @@`
				`bash: .agent/validate.sh: No such file or directory`