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 checks pass. The diff is complete and correct — panel logic fully moved to `header.js`, `app.js` keeps only the chat-specific Tune form wired to the module, comments updated, markup/API/styles untouched.
+
+## Report
+
+**Implemented (task 01 — steering moves to module):**
+- `header.js` now owns the steering controls: null-safe element refs, `renderSteeringPanel()` (newest-first, textContent XSS contract, labeled delete), `deleteSteeringNote()`, toggle click binding (exact phase-15 behavior — no Esc/outside-click existed), count badge + announcer; exports `refreshSteering()` (fetch+render, non-2xx/unreachable → empty state) and `announceSteering()`; `initSharedHeader()` gates the surface — admin → fire-and-forget boot refresh (count badge), anonymous → toggle+panel removed from DOM (phase-16 "absent, not hidden"; `/api/steering` never fetched)
+- `app.js`: panel section deleted (refs, `loadSteering`/`renderSteeringPanel`/`deleteSteeringNote`/`setSteeringPanel`, toggle binding, anonymous removal); per-bubble Tune button + inline form kept, save path now calls `refreshSteering()`/`announceSteering()` from the module; comments updated (app.js, index.html)
+- 4 new source-level unit pins in `tests/unit/test_shared_header.py`
+
+**Results:**
+- `uv run pytest tests/unit tests/integration` — 555 passed, 0 failed (JUnit-verified)
+- `uv run pytest --cov=app` — TOTAL **99%** (>90% gate)
+- `uv run ruff check . && uv run pyright` — clean
+- E2E regressions run in isolation, all green: `test_steering` + `test_admin_auth` (10), `test_shared_header` + `test_global_tuning` + `test_header_consistency` + `test_chat_rag` (18), `test_sync_button` + `test_tuning_nav_link` + `test_document_back_navigation` + `test_document_viewer` + `test_smoke` (20)
+
+**Decisions:** anonymous removal + boot refresh moved into `initSharedHeader()` (module owns the controls it gates) — this is what allows the chat page to keep working with zero page-script duplication; no commit made — the phase's single `--no-gpg-sign` commit belongs to task 05.
+
+**Next pending task:** `.agents/phases/todo/34_consistent_navbar/02_sync_and_chat_moves_to_module.md`
@@ -0,0 +1,53 @@
+........................................................................ [ 12%]
+........................................................................ [ 25%]
+........................................................................ [ 38%]
+........................................................................ [ 51%]
+........................................................................ [ 64%]
+........................................................................ [ 77%]
+........................................................................ [ 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            103      0   100%
+app/api/docs.py             23      0   100%
+app/api/health.py           10      0   100%
+app/api/steering.py         42      0   100%
+app/api/suggestions.py       8      0   100%
+app/api/sync.py             67      0   100%
+app/config.py               64      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/caching.py         92      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                 40      0   100%
+app/models.py               53      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        173      3    98%
+app/rag/llm.py             118      0   100%
+app/rag/overview.py         71      0   100%
+app/rag/prompts.py          64      0   100%
+app/rag/retriever.py        94      3    97%
+app/rag/suggestions.py      27      0   100%
+app/rag/summarizer.py       24      0   100%
+app/schemas.py              68      0   100%
+--------------------------------------------
+TOTAL                     1453     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,12 @@
+Everything is green and the working tree contains only this phase's files. Task 02 is complete.
+
+**Task 02 — sync state machine + New chat + sign-in `?next=` into `header.js`**
+
+- `header.js` now owns: the sync state machine (admin-only boot re-attach on the cached whoami, POST 202/409, single 2 s poll, no hard timeout, `Synced HH:MM`/failed states with sanitized error in `title`+`aria-label`+`.is-error`), dispatching `bor:sync-status` (detail = status object) on every state change incl. the immediate synthetic `running` frame on click; the single `#new-chat-btn` binding (chat → `bor:new-chat` event; else clear+navigate); sign-in `href` rewritten to `/login.html?next=<pathname>` in `initSharedHeader()`; `fmtSyncResult` exported for one counts implementation.
+- `app.js` acts off `bor:new-chat`; `sources.js` keeps only the event-driven `#sync-result`/`#sync-error-banner` (+ `loadDocs()` on success); `tuning.js`/`document.js` bindings removed; unit pins re-targeted.
+- Fixed pre-existing defect: `test_caching.py` fixture commits now pass `-c commit.gpgsign=false` (2 baseline failures from env GPG signing).
+- Fixed a real defect found while verifying: a new run now clears the previous failure's `title`/`aria-label`/`.is-error` in the running state.
+- `uv run pytest --cov=app`: **561 passed, TOTAL 99%** (>90%, unchanged); `ruff` clean; `pyright` 0 errors.
+- E2E in isolation: `test_sync_button` 3✓, `test_shared_header` 6✓, `test_chat_persistence` 4✓, `test_chat_rag` 3✓, `test_header_consistency` 3✓, `test_document_back_navigation` 3✓, `test_document_viewer` 7✓, `test_steering` 4✓, `test_global_tuning` 6✓, `test_tuning_nav_link` 4✓, `test_smoke` 3✓; live-verified sync failed/success/reload-re-attach + sign-in round-trip + zero console errors on all 5 pages (both roles).
+- Known/expected: `test_admin_auth.py` has 1 assertion failing on the old static chat-page `?next=/sources.html` — the task's ASSUMPTION changes it to `?next=/` at runtime; task 05 updates that suite (5/6 pass).
+- Next pending task: `03_full_header_all_pages.md`.
@@ -0,0 +1,53 @@
+........................................................................ [ 12%]
+........................................................................ [ 25%]
+........................................................................ [ 38%]
+........................................................................ [ 51%]
+........................................................................ [ 64%]
+........................................................................ [ 77%]
+........................................................................ [ 89%]
+.........................................................                [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            103      0   100%
+app/api/docs.py             23      0   100%
+app/api/health.py           10      0   100%
+app/api/steering.py         42      0   100%
+app/api/suggestions.py       8      0   100%
+app/api/sync.py             67      0   100%
+app/config.py               64      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/caching.py         92      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                 40      0   100%
+app/models.py               53      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        173      3    98%
+app/rag/llm.py             118      0   100%
+app/rag/overview.py         71      0   100%
+app/rag/prompts.py          64      0   100%
+app/rag/retriever.py        94      3    97%
+app/rag/suggestions.py      27      0   100%
+app/rag/summarizer.py       24      0   100%
+app/schemas.py              68      0   100%
+--------------------------------------------
+TOTAL                     1453     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,14 @@
+All done. Final report:
+
+**Phase 34 · Task 03 — full header on all five pages — complete**
+
+- Shipped the identical header block (brand, nav [Chat/Sources/Tuning], `#steering-toggle`, `#sync-btn`, `#new-chat-btn`, Sign in/out) on all five pages; `#steering-panel` + `#steering-announcer` on every page (viewer included — objective says "all five", work item 4 only described the header)
+- `document.html`: two-row header — `<header.doc-header>` wrapping row 1 `<div.app-header>` (byte-identical controls, no `is-active`) + row 2 `.doc-titlebar` (`#doc-back`/`#doc-title`/`#doc-meta`); old `.doc-header-actions` dropped
+- `login.html` gains the full header (incl. `#nav-tuning`, sign-in fallback `?next=/login.html`); `header.js`/`document.js`/`login.js` stale "no nav / no controls" comments updated — no behavior change
+- Unit tests: flipped 2 old-contract tests, extended nav test to 5 pages, added control-order + steering-panel tests
+- GATES: `uv run pytest` 563 passed · `uv run pytest --cov=app` TOTAL 99% (unchanged) · `ruff check .` clean · `pyright` 0 errors
+- Browser smoke (Playwright, seeded fixtures): 5 pages × admin/anonymous — full/reduced bar, per-page `?next=` rewrite, steering panel open/close on viewer, zero console errors
+
+**Notable:** Sources' `#sync-btn` moved before New chat (canonical order per completion criteria; `#sync-result` stays adjacent, unit pins hold). Pre-existing `test_admin_auth` failure from task 02's `?next=` rewrite fixed (chat now asserts `/login.html?next=/`). 4 `test_shared_header.py` E2E failures remain — all the one "viewer has no nav" assertion task 05 flips; every other regression-suite green in isolation. No commit (phase commit is task 05).
+
+**Next task:** `34_consistent_navbar/04_viewer_titlebar_styles.md`
@@ -0,0 +1,53 @@
+........................................................................ [ 12%]
+........................................................................ [ 25%]
+........................................................................ [ 38%]
+........................................................................ [ 51%]
+........................................................................ [ 63%]
+........................................................................ [ 76%]
+........................................................................ [ 89%]
+...........................................................              [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            103      0   100%
+app/api/docs.py             23      0   100%
+app/api/health.py           10      0   100%
+app/api/steering.py         42      0   100%
+app/api/suggestions.py       8      0   100%
+app/api/sync.py             67      0   100%
+app/config.py               64      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/caching.py         92      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                 40      0   100%
+app/models.py               53      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        173      3    98%
+app/rag/llm.py             118      0   100%
+app/rag/overview.py         71      0   100%
+app/rag/prompts.py          64      0   100%
+app/rag/retriever.py        94      3    97%
+app/rag/suggestions.py      27      0   100%
+app/rag/summarizer.py       24      0   100%
+app/schemas.py              68      0   100%
+--------------------------------------------
+TOTAL                     1453     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+All green. Task 04 complete.
+
+**Implemented**
+- Two-row viewer header CSS: `.doc-header` is now a content-sized sticky wrapper (both rows pinned); row 1 reuses `.app-header`/`.header-inner` verbatim (64/58px); new `.doc-titlebar` (container row, back pill, title+meta, `--line` border-top, gradient hairline kept at the header's bottom edge); removed dead `.doc-header-inner`/`.doc-header-actions` rules
+- `#doc-title` ellipsis + `title` attribute (document.js; cleared on not-found)
+- Failed-sync look: `.sync-btn.is-error` in the phase-08 error pair (`#fca5a5`/`#2d1318`, `--err-line` border) — visible on every page
+- Visual-pass fixes: steering panel pinned to the 72rem column on non-chat pages; full admin bar now fits 360/375/768px (brand wordmark = designated squeeze target; added ≤900px tablet squeeze) — two pre-existing task-03 overflows (375 all pages, 768 Sources) fixed
+
+**Verification**
+- `uv run pytest` → 564 passed; `--cov=app` TOTAL **99%**; `ruff check .` + `pyright` clean
+- Visual pass (admin+anon, 1280/768/375/360, all 5 pages): row 1 = 64/58px identical to chat/sources bars, titlebar 74.8/70.6px, sticky, no overflow, no console errors, sync-failed + login + panel checked
+- E2E in isolation: document_viewer (7), back_navigation (3), sync_button (3), admin_auth (6), responsive_polish (7), smoke (3), chat_rag (3), dark_tech_theme (6), global_tuning (6), tuning_nav_link (4) — all pass
+
+**Notes**
+- `tests/unit/test_shared_header.py` viewer-CSS test rewritten to the two-row contract (old assertion conflicted with task 04); `test_shared_header.py`/`test_header_consistency.py` e2e still fail only on the stale old-viewer assertions task 05 explicitly updates
+
+**Next pending task:** `.agents/phases/todo/34_consistent_navbar/05_e2e_and_contract_update.md`
@@ -0,0 +1,53 @@
+........................................................................ [ 12%]
+........................................................................ [ 25%]
+........................................................................ [ 38%]
+........................................................................ [ 51%]
+........................................................................ [ 63%]
+........................................................................ [ 76%]
+........................................................................ [ 89%]
+............................................................             [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            103      0   100%
+app/api/docs.py             23      0   100%
+app/api/health.py           10      0   100%
+app/api/steering.py         42      0   100%
+app/api/suggestions.py       8      0   100%
+app/api/sync.py             67      0   100%
+app/config.py               64      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/caching.py         92      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                 40      0   100%
+app/models.py               53      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        173      3    98%
+app/rag/llm.py             118      0   100%
+app/rag/overview.py         71      0   100%
+app/rag/prompts.py          64      0   100%
+app/rag/retriever.py        94      3    97%
+app/rag/suggestions.py      27      0   100%
+app/rag/summarizer.py       24      0   100%
+app/schemas.py              68      0   100%
+--------------------------------------------
+TOTAL                     1453     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,11 @@
+Everything is complete and verified. Final report:
+
+**Phase 34 task 05 — done**
+
+- **New story gate** `tests/e2e/test_nav_consistency.py` (6 tests): identical visible header-control inventory (id+class, DOM order, normalized for `is-active`/`?next=`) on all 5 pages for **admin** and **anonymous**; viewer row-1 height == chat bar (64px/58px) + titlebar row with back/title/meta; `#doc-back` `back=` param positive + rejection (by click); steering toggle open/close off-chat on `/tuning.html` (zero notes, count badge 0); `#sync-btn` present, never triggered.
+- **Contract suites updated**: `test_header_consistency.py` + `test_shared_header.py` now measure viewer row 1 (`.doc-header .app-header`) and assert the viewer's full nav contract (was "no nav").
+- **Defect fixed** (prior task's work): `login.js` admin branch redirected **before** `initSharedHeader()`, so the admin login bar was never settled — both branches now settle the bar (redirect preserved; unit-pinned assertions intact).
+- **Results**: `uv run pytest tests/e2e/test_nav_consistency.py -v --no-cov` → 6 passed in isolation; all 11 required regressions green in isolation (plus the other 19 E2E suites run as a repo-health check); `uv run pytest` → 564 passed; `--cov=app` TOTAL **99%** (>90%, unchanged — no `app/` change); `ruff check .` + `pyright` clean.
+- **Deviation**: task bullet "anonymous: `#steering-toggle` visible" conflicts with the locked phase-16 "absent, not hidden" contract (pinned by `test_admin_auth.py` on the regression list + task 01's unit tests) — the suite asserts **absent** (count 0) for anonymous, per the locked behavior.
+- **Commit**: `b2d8696 feat(ui): one consistent navbar on every page (TODO.md L3)` (`--no-gpg-sign`, 19 files: `frontend/**` + `tests/**`); phase dir moved to `.agents/phases/complete/34_consistent_navbar/`.
+- **Next pending task**: `.agents/phases/todo/35_git_sources_admin/` (top of the queue).
@@ -0,0 +1,53 @@
+........................................................................ [ 12%]
+........................................................................ [ 25%]
+........................................................................ [ 38%]
+........................................................................ [ 51%]
+........................................................................ [ 63%]
+........................................................................ [ 76%]
+........................................................................ [ 89%]
+............................................................             [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            103      0   100%
+app/api/docs.py             23      0   100%
+app/api/health.py           10      0   100%
+app/api/steering.py         42      0   100%
+app/api/suggestions.py       8      0   100%
+app/api/sync.py             67      0   100%
+app/config.py               64      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/caching.py         92      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                 40      0   100%
+app/models.py               53      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        173      3    98%
+app/rag/llm.py             118      0   100%
+app/rag/overview.py         71      0   100%
+app/rag/prompts.py          64      0   100%
+app/rag/retriever.py        94      3    97%
+app/rag/suggestions.py      27      0   100%
+app/rag/summarizer.py       24      0   100%
+app/schemas.py              68      0   100%
+--------------------------------------------
+TOTAL                     1453     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK