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,12 @@
+All criteria verified with executed assertions — no defects found, no fixes needed. Final report:
+
+**Phase 41 verification pass — all green (implementation + commit already in place; nothing to fix)**
+
+- Verified: `check_models()` probe in `app/rag/llm.py` (embed + summary, `ModelUnavailableError` names the dead model), called first in `_run_sync` before source resolution/clones; module-owned modal in `header.js` (`alertdialog`, `aria-modal`, `textContent`, ×/Esc/backdrop close, focus in→`#sync-btn`→out), `.sync-modal` CSS with error palette + reduced-motion; `applySyncFailure` byte-compatible with the phase-32 event contract.
+- `uv run pytest --cov=app --cov-report=term-missing` → **721 passed**, app/ coverage **99%** (gate >90%)
+- `uv run pytest tests/e2e/test_sync_model_down.py -v --no-cov` → **4 passed** in isolation (fail-fast ≤10 s vs clone budget, model-naming modal, all 3 dismissal paths, Sources banner, healthy clone→import→overview run)
+- Regressions in isolation: `test_sync_button.py` **3 passed**, `test_git_sources_admin.py` **6 passed**, `test_local_directory_sources.py` **3 passed**
+- `uv run ruff check . && uv run pyright` → **All checks passed / 0 errors**
+- Commit `6cf1df9 feat(sync): fail fast with a modal when a model is unavailable` present (9 files, Conventional Commits, `--no-gpg-sign` per repo config); task files already in `.agents/phases/complete/`, `00_phase.md` left for the harness to move
+- Locked decisions honored: A12 in-process, A10 no new endpoint, phase-32 contract (2 s poll, 202/409, `bor:sync-status`) unchanged
+- No deviations. Next pending phase: **`42_no_reply_autoscroll`**
@@ -0,0 +1,60 @@
+........................................................................ [  9%]
+........................................................................ [ 19%]
+........................................................................ [ 29%]
+........................................................................ [ 39%]
+........................................................................ [ 49%]
+........................................................................ [ 59%]
+........................................................................ [ 69%]
+........................................................................ [ 79%]
+........................................................................ [ 89%]
+........................................................................ [ 99%]
+.                                                                        [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            122      0   100%
+app/api/config.py            7      0   100%
+app/api/docs.py             23      0   100%
+app/api/git_sources.py      66      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             81      0   100%
+app/config.py               66      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                 44      0   100%
+app/models.py               60      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/agent.py            81      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/git_sources.py      14      0   100%
+app/rag/importer.py        173      3    98%
+app/rag/llm.py             186      0   100%
+app/rag/overview.py         71      0   100%
+app/rag/prompts.py          65      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              99      0   100%
+--------------------------------------------
+TOTAL                     1767     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+Task complete — all criteria met. Final report:
+
+**Phase 41 / Task 01 — model probe fail-fast: implemented**
+- `app/rag/llm.py`: `ModelUnavailableError(LLMError)` + `check_models(llm)` — probes `embed_one("sync model check")` then `chat("ping")` (summary model default); wraps any failure in `ModelUnavailableError` naming the model from settings, original exception chained.
+- `app/api/sync.py`: `llm = LLMClient()` + `await check_models(llm)` is now step 1 of `_run_sync` (before `effective_sources`, before any clone); client reused for import + overview; module docstring pipeline renumbered (probe = step 1).
+- `tests/fakes.py`: `FakeEmbedder.embed_one` added (delegates to `embed`) so existing stubs satisfy the probe.
+- `tests/unit/test_sync_model_probe.py` (new, 9 tests): both-up, embed-down (chat never reached), chat-down, arbitrary-exception wrapping, message wording/model-name assertions, custom model names.
+- `tests/integration/test_sync_api.py`: `_stub_probe` helper added to all real-`LLMClient` tests; new tests — probe-stub fail-fast (error verbatim, sanitizer no-op, zero clones/imports), real probe vs dead `_DeadEmbedder` (model named + credentials masked), spy ordering probe→`effective_sources`; success test asserts probe/import/overview share one client.
+
+**Results**
+- `uv run pytest --cov=app --cov-report=term-missing` → 713 passed; TOTAL **99%** (>90%); `llm.py`/`sync.py` 100%
+- `uv run ruff check . && uv run pyright` → clean (0 errors)
+- Sanity: `uv run pytest tests/e2e/test_sync_button.py -v --no-cov` → 3 passed (healthy pipeline unchanged)
+
+**Decisions:** no commit (belongs to task 03 per phase plan); probe messages include the wrapped exception so the endpoint reason survives — the sync sanitizer masks any embedded credentials.
+
+**Next pending task:** `.agents/phases/todo/41_sync_fail_fast_models/02_sync_error_modal.md`
@@ -0,0 +1,59 @@
+........................................................................ [ 10%]
+........................................................................ [ 20%]
+........................................................................ [ 30%]
+........................................................................ [ 40%]
+........................................................................ [ 50%]
+........................................................................ [ 60%]
+........................................................................ [ 70%]
+........................................................................ [ 80%]
+........................................................................ [ 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            122      0   100%
+app/api/config.py            7      0   100%
+app/api/docs.py             23      0   100%
+app/api/git_sources.py      66      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             81      0   100%
+app/config.py               66      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                 44      0   100%
+app/models.py               60      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/agent.py            81      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/git_sources.py      14      0   100%
+app/rag/importer.py        173      3    98%
+app/rag/llm.py             186      0   100%
+app/rag/overview.py         71      0   100%
+app/rag/prompts.py          65      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              99      0   100%
+--------------------------------------------
+TOTAL                     1767     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,16 @@
+All green. Final state verified — reporting:
+
+**Task 02 (sync error modal) — complete**
+
+- `frontend/assets/header.js`: `showSyncModal(error)` + lazily-created modal (`let syncModal = null`, backdrop + `role="alertdialog"` panel appended to `<body>` once), error via `textContent` only, in-place update on repeat failure, close via button/Esc(document keydown while open)/backdrop-self click through one `closeSyncModal()`, focus in→close button and out→remembered `#sync-btn`; called from `applySyncFailure` **after** the byte-identical title/aria/`.is-error` + `emitSyncStatus` lines; module + sync-section docstrings updated
+- `frontend/assets/styles.css`: `.sync-modal-backdrop` (fixed, rgba dim, `z-index:1000`) + `.sync-modal` (28rem, phase-08 error palette `--err-bg`/`--err-line`/`--err-ink`, `--ink` title), `.is-open` visibility/opacity, 44px close button, reduced-motion stilling
+- `tests/unit/test_sync_button.py`: 5 new house-style source pins (alertdialog markup, textContent + in-place ordering, focus in/out, Esc/backdrop/button closes, `showSyncModal` after `emitSyncStatus`, CSS palette/stacking/touch-floor/reduced-motion)
+- Node DOM-stub smoke test caught & fixed a real bug: `createSyncModal` was missing `return backdrop` (pinned now)
+
+**Results**
+- `uv run pytest tests/unit/test_sync_button.py --no-cov` → 33 passed
+- `uv run pytest --cov=app --cov-report=term` → 721 passed, TOTAL **99%** (>90%)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+- No page HTML changed, no CDN (A11); `node --check` on header.js OK
+
+**Next pending task:** `.agents/phases/todo/41_sync_fail_fast_models/03_model_down_e2e_and_commit.md` (E2E suite + commit)
@@ -0,0 +1,60 @@
+........................................................................ [  9%]
+........................................................................ [ 19%]
+........................................................................ [ 29%]
+........................................................................ [ 39%]
+........................................................................ [ 49%]
+........................................................................ [ 59%]
+........................................................................ [ 69%]
+........................................................................ [ 79%]
+........................................................................ [ 89%]
+........................................................................ [ 99%]
+.                                                                        [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            122      0   100%
+app/api/config.py            7      0   100%
+app/api/docs.py             23      0   100%
+app/api/git_sources.py      66      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             81      0   100%
+app/config.py               66      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                 44      0   100%
+app/models.py               60      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/agent.py            81      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/git_sources.py      14      0   100%
+app/rag/importer.py        173      3    98%
+app/rag/llm.py             186      0   100%
+app/rag/overview.py         71      0   100%
+app/rag/prompts.py          65      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              99      0   100%
+--------------------------------------------
+TOTAL                     1767     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+Task 03 complete. Final report:
+
+**Implemented**
+- `tests/e2e/test_sync_model_down.py` (new): two module-scoped apps on distinct ports — dead-model app on `APP_PORT+41` (`BOR_LLM_BASE_URL=http://127.0.0.1:9/v1`, closed loopback port) pointed at a real `file://` fixture repo, healthy app on `APP_PORT` with the session mock. Covers: ≤10 s fail-fast before any clone + `role="alertdialog"`/`aria-modal` modal naming the embed model; all three dismissal paths (×, Esc, backdrop) with focus in-and-out to `#sync-btn`; button `title`/`aria-label`/`.is-error` + Sources `#sync-error-banner` off `bor:sync-status`; healthy phase-32 lifecycle regression ("1 added" → "Synced HH:MM" → idempotent "0 added · 1 unchanged", `kb_overview` fresh, no modal).
+- **Defect fixed (task 02):** `showSyncModal` remembered `document.activeElement`, but the run's disabled button drops focus to `<body>` — focus-out went to body, not `#sync-btn`. Now falls back to `#sync-btn` when active element is body; unit pin updated to match.
+
+**Results (exact commands)**
+- `uv run pytest tests/e2e/test_sync_model_down.py -v --no-cov` → 4 passed, in isolation
+- `uv run pytest tests/e2e/test_sync_button.py -v --no-cov` → 3 passed; `…/test_git_sources_admin.py` → 6 passed; `…/test_local_directory_sources.py` → 3 passed (each in isolation)
+- `uv run pytest --cov=app --cov-report=term-missing` → 721 passed, `app/` TOTAL **99%** (>90%)
+- `uv run ruff check . && uv run pyright` → all checks passed / 0 errors
+
+**Decisions**
+- E2E tests 2–3 first close the *re-attach* modal (a page load re-enters the dead app's last `failed` state and opens the modal — correct product behavior).
+- Committed `6cf1df9 feat(sync): fail fast with a modal when a model is unavailable` (`--no-gpg-sign`, 9 files — phase 01/02/03 work). Phase dir not moved per harness protocol.
+
+**Next pending:** phase 41 is fully done; next in queue is `42_no_reply_autoscroll`.
@@ -0,0 +1,60 @@
+........................................................................ [  9%]
+........................................................................ [ 19%]
+........................................................................ [ 29%]
+........................................................................ [ 39%]
+........................................................................ [ 49%]
+........................................................................ [ 59%]
+........................................................................ [ 69%]
+........................................................................ [ 79%]
+........................................................................ [ 89%]
+........................................................................ [ 99%]
+.                                                                        [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            122      0   100%
+app/api/config.py            7      0   100%
+app/api/docs.py             23      0   100%
+app/api/git_sources.py      66      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             81      0   100%
+app/config.py               66      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                 44      0   100%
+app/models.py               60      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/agent.py            81      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/git_sources.py      14      0   100%
+app/rag/importer.py        173      3    98%
+app/rag/llm.py             186      0   100%
+app/rag/overview.py         71      0   100%
+app/rag/prompts.py          65      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              99      0   100%
+--------------------------------------------
+TOTAL                     1767     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK