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

Standardize on the .agents/ directory (shared with project skills): phases/, user_stories/, reports/, screenshots/, validate.sh, and phase-sessions/ + pipeline.log all move to .agents/ (git mv preserves history; runtime artifacts move alongside). Updates every reference in AGENTS.md, README.md, .gitignore, app docstrings, and test story headers. Historical KB content in data/ and the runtime pipeline.log transcript are left untouched.
2026-09-05 10:57:07 -04:00
parent 766702c750
commit dbf2af26c6
1118 changed files with 664 additions and 664 deletions
@@ -0,0 +1,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**: `.agents/phases/todo/19_shared_header/02_e2e_story_suite.md`
@@ -0,0 +1 @@
+bash: .agents/validate.sh: No such file or directory
@@ -0,0 +1,14 @@
+**Fixed this attempt**
+- Recreated the missing `.agents/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 .agents/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**: `.agents/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 `.agents/` changes needed — task 01's implementation passed the whole suite as-is
+
+**Next pending task:** `.agents/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**
+- `.agents/PLAN.md` restored (it had been removed from the tree by the "uncommit .agents" 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
+- `.agents/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/`: `.agents/` 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 @@`
				`bash: .agents/validate.sh: No such file or directory`