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.

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__00_phase.a1.md

@@ -0,0 +1,20 @@
+All verification passed — no defects found. Final report:
+
+**Phase 31 (kb-overview-prompt) — final verification pass: all green**
+
+Verified (implemented in commit `0654b30`, no changes needed this pass):
+- Migration 0005 `kb_overview` single-row table — live DB schema confirmed
+- `app/rag/overview.py`: `KB_OVERVIEW_MODE` prompt, `load_kb_overview`, best-effort change-gated `regenerate_overview`
+- `<knowledge_base>` section in HIGH+LOW prompts (budgeted, byte-identical when absent, ordered `<relevance>`→`<knowledge_base>`→`<tuning>`→body)
+- Import trigger: `overview=updated|skipped|failed` on summary line; unchanged/`--limit` re-imports skip the lite call
+- Mock `(kb: …)` echo + dedicated E2E story file
+
+Test / lint / coverage:
+- `uv run pytest --cov=app --cov-report=term-missing` → 436 passed; TOTAL **99%** (>90% ✓)
+- `uv run pytest tests/e2e/test_kb_overview.py -v --no-cov` → 4 passed in isolation ✓
+- `uv run ruff check . && uv run pyright` → clean (0 errors) ✓
+- Prompt/steering/chat suites green within full run; `test_no_overview_prompt_is_byte_identical_to_pre_phase`, `kb_chars` log, and unchanged-reimport no-lite-call all asserted ✓
+
+Completion criteria: all 8 met (docs in `.env.example` + README ✓, story file ✓, single `--no-gpg-sign` commit staging only this phase ✓).
+
+Notable: live DB has 0 `kb_overview` rows — expected; rows are created on the next real import (E2E/integration fixtures use the mock). Next pending phase: `32_admin_sync_button`.

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__00_phase.a1.validate

@@ -0,0 +1,50 @@
+........................................................................ [ 14%]
+........................................................................ [ 29%]
+........................................................................ [ 44%]
+........................................................................ [ 59%]
+........................................................................ [ 73%]
+........................................................................ [ 88%]
+........................................................                 [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/config.py               64      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               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                     1290     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__01_migration_kb_overview.a1.md

@@ -0,0 +1,18 @@
+Task 01 complete. All gates green.
+
+**Implemented**
+- `alembic/versions/0005_kb_overview.py` — single-row `kb_overview` table (`id INTEGER PK` default 1, `content TEXT NOT NULL` default `''`, `updated_at TIMESTAMPTZ NOT NULL` default `now()`); downgrade drops it
+- `app/models.py` — `KbOverview` model (single-row, lite-generated KB outline, phase 31) + module docstring entry
+- `tests/integration/test_migration_0005.py` — 4 tests in the 0002/0004 style: column contract (types/nullability/server defaults/PK), bare-insert single-row defaults, downgrade drops table, round-trip restores
+- Fixed defect from phase 30 work: `tests/integration/test_migration_0004.py` hardcoded `0004` as head (`upgrade "head"` → `assert version == "0004"`) — now targets revision `0004` explicitly so later migrations can't break it
+
+**Results**
+- `uv run alembic upgrade head` / `downgrade -1` / `upgrade head` — clean; dev DB at `0005 (head)`
+- `uv run pytest --cov=app --cov-report=term-missing` — 438 passed; app/ TOTAL 99% (>90%, `models.py` 100%)
+- `uv run ruff check . && uv run pyright` — clean (0 errors)
+- ORM smoke check: `KbOverview()` insert lands `id=1, content=''`, server-stamped `updated_at` (row cleaned up)
+
+**Decisions**
+- No commit made: the phase's one atomic `--no-gpg-sign` commit is task 05's step (AGENTS.md §8 — one commit per completed phase); working tree left staged for the pipeline
+
+**Next pending task:** `31_kb_overview_prompt/02_overview_generator.md`

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__01_migration_kb_overview.a1.validate

@@ -0,0 +1,49 @@
+........................................................................ [ 16%]
+........................................................................ [ 32%]
+........................................................................ [ 49%]
+........................................................................ [ 65%]
+........................................................................ [ 82%]
+........................................................................ [ 98%]
+......                                                                   [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             98      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/config.py               62      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               53      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        173      5    97%
+app/rag/llm.py             118      0   100%
+app/rag/prompts.py          44      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                     1192     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__02_overview_generator.a1.md

@@ -0,0 +1,14 @@
+Task 02 is complete and everything is green. Final report:
+
+**Implemented (phase 31, task 02 — KB overview generator):**
+- `app/config.py`: `kb_overview_max_chars` (4000, `BOR_KB_OVERVIEW_MAX_CHARS`) + `overview_input_max_chars` (40000, `BOR_OVERVIEW_INPUT_MAX_CHARS`) — env mapping verified
+- `app/rag/overview.py`: `KB_OVERVIEW_MODE` marker + locked `OVERVIEW_INSTRUCTION`; `build_overview_prompt` (per-doc `source — path — title — first summary line`, cap → shared `TRUNCATION_MARKER`, summarizer convention); `load_kb_overview` (single PK lookup, trimmed, `""` when absent); `regenerate_overview` (best-effort, id=1 upsert, zero-docs → no model call/False, `LLMError` → fail-soft, `session=None` owns a private session like `import_sources`; logs `overview: regenerated docs=… chars=…` / `overview: regeneration failed — …`)
+- `tests/unit/test_overview.py`: 21 tests — prompt build/cap/ordering, loader, regenerate happy/zero-docs/fail-soft/idempotent/own-session, with a duck-typed fake LLM (test_steering/test_summarizer style; real Postgres via the shared `db` fixture per test_importer precedent — SQLite infeasible due to pgvector/UUID columns)
+
+**Results:**
+- `uv run pytest --cov=app --cov-report=term-missing` → 459 passed; TOTAL 99% (`app/rag/overview.py` 100%)
+- `uv run ruff check . && uv run pyright` → clean / 0 errors
+
+**Decisions:** doc line omits the summary field when absent (no dangling dash); first *non-blank* summary line used; failure logged at ERROR (matches importer fail-soft). No deviations.
+
+**Next pending task:** `03_prompt_injection.md` (phase 31) — `<knowledge_base>` section in HIGH+LOW prompts + `kb_chars` log.

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__02_overview_generator.a1.validate

@@ -0,0 +1,50 @@
+........................................................................ [ 15%]
+........................................................................ [ 31%]
+........................................................................ [ 47%]
+........................................................................ [ 62%]
+........................................................................ [ 78%]
+........................................................................ [ 94%]
+...........................                                              [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             98      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/config.py               64      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               53      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        173      5    97%
+app/rag/llm.py             118      0   100%
+app/rag/overview.py         71      0   100%
+app/rag/prompts.py          44      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                     1265     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__03_prompt_injection.a1.md

@@ -0,0 +1,13 @@
+All green. Task 03 is complete.
+
+**Report — Phase 31, Task 03: `<knowledge_base>` prompt section + chat wiring**
+
+- `app/rag/prompts.py`: new `build_kb_section()` (empty→`""`, budgeted at `BOR_KB_OVERVIEW_MAX_CHARS` with shared `[…truncated…]` marker, exact `build_steering_section` pattern incl. pathological-budget handling); `build_high_prompt`/`build_deflect_prompt` take `kb_overview=` and insert `<knowledge_base>` in the locked order `<relevance>` → `<knowledge_base>` → `<tuning>` → mode body.
+- `app/api/chat.py`: per-turn `load_kb_overview(db)` (one PK lookup, no LLM call) next to the steering load; `plan_turn(..., kb_overview=)`; `TurnPlan.kb_chars` (outline length, 0 when absent); per-turn log line now `… tuning=%d kb_chars=%d threshold=…`.
+- Tests: `test_prompts.py` +13 (builder contract, cap/marker, default settings budget, pathological budgets, byte-identity for None/""/blank with and without notes, ordering in both modes, prompt-level cap); `test_chat_gate.py` +5 (both `plan_turn` branches carry the section + `kb_chars`, empty overview → 0 + unchanged prompt, endpoint-level injection + `kb_chars=` log assertion; `_FakeSession` gained `get`).
+- Verified byte-identity against the actual pre-phase (git HEAD) builders: 56 doc/notes/overview combinations identical.
+- `uv run pytest` → 478 passed (baseline 459). `uv run pytest --cov=app --cov-report=term-missing` → 478 passed, TOTAL 99% (1290 stmts, same 14 misses as pre-change; `prompts.py`/`chat.py` 100%).
+- `uv run ruff check .` → all checks passed; `uv run pyright` → 0 errors.
+- Sanity: `uv run pytest tests/e2e/test_chat_rag.py -v --no-cov` → 3 passed in isolation (real-stack SSE path unaffected with no overview row).
+- No deviations. `.env.example`/README docs for the new settings are owned by tasks 04/05, not started.
+- Next pending task: `.agent/phases/todo/31_kb_overview_prompt/04_import_trigger.md`.

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__03_prompt_injection.a1.validate

@@ -0,0 +1,50 @@
+........................................................................ [ 15%]
+........................................................................ [ 30%]
+........................................................................ [ 45%]
+........................................................................ [ 60%]
+........................................................................ [ 75%]
+........................................................................ [ 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/config.py               64      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               53      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        173      5    97%
+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                     1290     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__04_import_trigger.a1.md

@@ -0,0 +1,19 @@
+All green. Task 04 is complete.
+
+**Implemented**
+- `scripts/import_docs.py`: `main()` now runs one `async def _run()` — `import_sources(…)` followed by change-gated `regenerate_overview(llm)` (one event loop, same `LLMClient`); gate skips on `--limit` (logs `overview: skipped (--limit)`), on unchanged re-imports with an existing row, and on empty walks; final print ends `overview=updated|skipped|failed`; exit code driven only by file errors (failed outline never fails the import). Added `_overview_row_exists()` (one indexed PK lookup).
+- `tests/integration/test_import_docs_overview.py` (new, 5 tests): real Postgres, fake LLM recording `chat`, git mocked (phase 28 style) — changed import → row + 1 chat call + `overview=updated`; unchanged re-import → no call + `skipped`; `LLMError` → rc 0 + `overview=failed` + previous row intact; `--limit` with changes → `skipped`; empty source, no row → nothing created, `skipped`.
+- `.env.example`: `BOR_KB_OVERVIEW_MAX_CHARS=4000`, `BOR_OVERVIEW_INPUT_MAX_CHARS=40000`; README: import-workflow bullet + two config-table rows.
+
+**Results**
+- `uv run pytest` → 483 passed (baseline 478 + 5)
+- `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 1290 stmts, 12 missing, 99% (baseline 14 missing — improved; `app/` gate met)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+- Manual dev-KB run: import of 521 docs logged `overview: regenerated docs=521 chars=7610`, printed `overview=updated`; unchanged re-run logged `overview: skipped (KB unchanged)`, printed `overview=skipped`
+
+**Decisions**
+- The "no row yet" clause requires the walk to have seen files (`files > 0`), so an empty-source run skips without a model call (task's 5th case) while a first post-migration-0005 unchanged run still creates the outline.
+- Tests attach a dedicated handler to `app.rag.overview` (caplog can't capture — `configure_logging` replaces root handlers inside `main()`).
+- No commit made — the phase commit belongs to task 05.
+
+**Next pending task:** `.agent/phases/todo/31_kb_overview_prompt/05_mock_and_e2e.md` (mock + E2E + story + phase commit).

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__04_import_trigger.a1.validate

@@ -0,0 +1,50 @@
+........................................................................ [ 14%]
+........................................................................ [ 29%]
+........................................................................ [ 44%]
+........................................................................ [ 59%]
+........................................................................ [ 74%]
+........................................................................ [ 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/config.py               64      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               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                     1290     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__05_mock_and_e2e.a1.md

@@ -0,0 +1 @@
+DB is up. Let me run the baseline test suite to confirm tasks 01–04 left things green.

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__05_mock_and_e2e.a1.validate

@@ -0,0 +1,50 @@
+........................................................................ [ 14%]
+........................................................................ [ 29%]
+........................................................................ [ 44%]
+........................................................................ [ 59%]
+........................................................................ [ 74%]
+........................................................................ [ 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/config.py               64      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               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                     1290     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__05_mock_and_e2e.a2.md

@@ -0,0 +1,12 @@
+**Phase 31 · Task 05 — complete** (commit `0654b30`, `--no-gpg-sign`)
+
+- Mock (`tests/e2e/mock_llm.py`): `KB_OVERVIEW_MODE` branch → byte-stable outline (first 8 tokens of the document list); `first_kb_bullet()` parser + `(kb: …)` echo appended on **all** answer paths after the steering echo.
+- Story E2E `tests/e2e/test_kb_overview.py` (4 tests): row seeded directly in DB → grounded answer **ends** with `(kb: Kubernetes cluster and node maintenance notes)`; deflected answer carries the same echo (section is in the LOW prompt); row deleted → no `(kb: …)` suffix; real `regenerate_overview` vs the mock proves the `KB_OVERVIEW_MODE` branch stores its 8-token digest and a turn echoes it.
+- Integration `tests/integration/test_kb_overview_api.py` (5 tests): capturing-fake pattern — no row ⇒ captured HIGH/LOW prompts **byte-equal** to `build_high_prompt`/`build_deflect_prompt(…, kb_overview=None)`; row present ⇒ exact construction with the outline in both modes + `kb_chars=N` log line; per-turn re-read + delete stops it.
+- Story file `.agent/user_stories/kb-overview-prompt.md` written (`.env.example`/README already done by tasks 02/04).
+
+**Results:** `uv run pytest` → 488 passed; `--cov=app` TOTAL 1290 stmts, 12 miss = **99%** (= pre-change); `tests/e2e/test_kb_overview.py -v --no-cov` → 4 passed in isolation; regressions in isolation: `test_steering` 4, `test_chat_rag` 3, `test_honest_deflection` 3 passed; `ruff check .` clean; `pyright` 0 errors.
+
+**Decisions:** kb echo appended after `(tuning: …)` so the "ends with" assertion holds even when both sections exist; E2E `_ask` waits on the echo (deflection answer has no mock marker); phase-30 `.agent` harness bookkeeping left unstaged per "only this phase's files".
+
+**Next pending:** `32_admin_sync_button/01_sync_api.md`.

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__05_mock_and_e2e.a2.validate

@@ -0,0 +1,50 @@
+........................................................................ [ 14%]
+........................................................................ [ 29%]
+........................................................................ [ 44%]
+........................................................................ [ 59%]
+........................................................................ [ 73%]
+........................................................................ [ 88%]
+........................................................                 [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/config.py               64      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               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                     1290     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__05_mock_and_e2e.a3.md

@@ -0,0 +1,13 @@
+All gates green — no code changes were needed this run; the prior rejection was a child-run/report glitch and all task-05 work had persisted (commit `0654b30`). Re-verified everything:
+
+**Phase 31 · Task 05 — verified green**
+- Mock: `KB_OVERVIEW_MODE` branch (byte-stable 8-token outline) + `first_kb_bullet()` `(kb: …)` echo on all answer paths (`tests/e2e/mock_llm.py`).
+- Story E2E `tests/e2e/test_kb_overview.py` (4 tests): direct DB row seed → grounded answer ends with `(kb: Kubernetes cluster and node maintenance notes)`; deflection echo present; row deleted → no echo; `regenerate_overview` vs mock round-trip.
+- Integration `tests/integration/test_kb_overview_api.py` (5 tests): no-row prompts byte-equal to pre-phase `build_high_prompt`/`build_deflect_prompt(kb_overview=None)`; row present → exact section in HIGH+LOW, `kb_chars=N` logged, per-turn re-read.
+- Story file `.agent/user_stories/kb-overview-prompt.md`; commit `0654b30` (`--no-gpg-sign`) stages only phase-31 files.
+
+**Results:** `uv run pytest` → 488 passed; `uv run pytest --cov=app` → TOTAL 1290 stmts, 12 miss = **99%** (≥ pre-change); E2E in isolation: `test_kb_overview` 4, `test_steering` 4, `test_chat_rag` 3, `test_honest_deflection` 3 passed; `uv run ruff check .` clean; `uv run pyright` 0 errors.
+
+**Decisions:** kb echo appended after `(tuning: …)`; phase-30 `.agent` bookkeeping left unstaged ("only this phase's files").
+
+**Next pending:** `32_admin_sync_button/01_sync_api.md`.

.agent/reports/31_kb_overview_prompt/31_kb_overview_prompt__05_mock_and_e2e.a3.validate

@@ -0,0 +1,50 @@
+........................................................................ [ 14%]
+........................................................................ [ 29%]
+........................................................................ [ 44%]
+........................................................................ [ 59%]
+........................................................................ [ 73%]
+........................................................................ [ 88%]
+........................................................                 [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/config.py               64      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               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                     1290     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK