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,20 @@
+All green. Task 01 is complete.
+
+## Report
+
+**Implemented**
+- `select_documents(chunks, n=None)` — removed `max_chars` param, budget, and truncation loop; returns deduped top-N docs with byte-identical content (A7 revised, owner permission 2026-08-24)
+- `TRUNCATION_MARKER` stays exported (steering `<tuning>` section, phase 15, unchanged)
+- `plan_turn` (HIGH + LOW paths) drop the budget argument; `max_context_chars` deleted from `app/config.py`; `BOR_MAX_CONTEXT_CHARS` line removed from `.env.example` and README settings table (steering mention at ~L178 untouched)
+- Unit tests: dropped `max_chars` from all `select_documents` calls; replaced 3 cap tests with `test_content_never_truncated_even_past_old_budget` (20k+15k=35k > old 24k cap, byte-identical, no marker); module docstring updated
+
+**Verification**
+- `rg "max_context" app/ tests/ .env.example README.md` → no matches
+- `uv run pytest tests/unit/test_retriever.py -v` → 14 passed
+- `uv run pytest` (unit+integration, testpaths per pyproject) → exit 0, all green
+- `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 99% (1099 stmts, 14 miss) — matches baseline, ≥90% gate
+- `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors
+
+**Decisions** — no deviations; no cap tests pinned elsewhere (verified by grep). No commit made (task 03 owns the commit); `.agents/`/`TODO.md` working-tree changes left as harness state.
+
+**Next pending task:** `02_whole_doc_e2e_suite.md`
@@ -0,0 +1,46 @@
+........................................................................ [ 21%]
+........................................................................ [ 43%]
+........................................................................ [ 64%]
+........................................................................ [ 86%]
+.............................................                            [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               55      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/debugging.py       29      2    93%
+app/core/logging.py         13      0   100%
+app/db.py                   21      0   100%
+app/main.py                 36      0   100%
+app/models.py               46      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        150      5    97%
+app/rag/llm.py             105      0   100%
+app/rag/prompts.py          44      0   100%
+app/rag/retriever.py        93      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1099     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,13 @@
+All gates are green. The `M TODO.md` is a new owner item landed after the conversion commit (out of scope for this task — will be captured as a future phase).
+
+**Task 02 complete — report**
+
+- **Mock** (`tests/e2e/mock_llm.py`): added `END_OF_NOTES_TRIGGER = "show the end of your notes"` (verified absent from all existing questions/fixtures) → `compose_answer` now echoes the last 160 chars of the context (byte-stable tail sentinel); branch sits after `DEFLECT_MODE`, before the generic path; docstring trigger list updated.
+- **New suite** (`tests/e2e/test_whole_document_context.py`, 3 tests): a 30k-char doc (past the old 24k cap) seeded via SQLAlchemy with mock-`embed_text` chunk vectors → tail sentinel + mock marker in bubble, no `[…truncated…]`, chip + `deflected=False`; a ~16k+~16k pair (32k combined) → the second doc's sentinel is echoed (order pinned: first doc's sentinel asserted absent), both chips, `deflected=False`; small-doc regression via the real importer (8 fixtures, `kubernetes.md` chip, no marker). No fixture files added.
+- **E2E (isolated):** `uv run pytest tests/e2e/test_whole_document_context.py -v --no-cov` → 3 passed, **twice consecutively** (pair ranking stable).
+- **E2E regressions:** `uv run pytest tests/e2e/test_chat_rag.py tests/e2e/test_honest_deflection.py -v --no-cov` → 6 passed; extra safety: `test_long_answers.py` + `test_steering.py` → 6 passed.
+- **Full suite/coverage:** `uv run pytest --cov=app --cov-report=term-missing` → 333 passed, **99%** on `app/` (>90% gate).
+- **Lint/types:** `uv run ruff check . && uv run pyright` → clean (0 errors).
+- **Fixtures:** `tests/fixtures/docs/` untouched (`git status` clean for that path).
+
+Next pending task: `.agents/phases/todo/24_whole_document_context/03_story_docs_plan_commit.md`.
@@ -0,0 +1,46 @@
+........................................................................ [ 21%]
+........................................................................ [ 43%]
+........................................................................ [ 64%]
+........................................................................ [ 86%]
+.............................................                            [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               55      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/debugging.py       29      2    93%
+app/core/logging.py         13      0   100%
+app/db.py                   21      0   100%
+app/main.py                 36      0   100%
+app/models.py               46      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        150      5    97%
+app/rag/llm.py             105      0   100%
+app/rag/prompts.py          44      0   100%
+app/rag/retriever.py        93      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1099     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,14 @@
+Committed as `1e6ae36`; working tree clean except the owner's uncommitted TODO.md input. All completion criteria met.
+
+**Report — Phase 24, Task 03 (final task) complete**
+
+- Wrote `.agents/user_stories/whole-document-context.md` (bug report verbatim, narrative, D1–D5 verbatim, acceptance criteria, Playwright mapping for the 3 tests).
+- Revised `.agents/PLAN.md`: A7 row now "(deduped)" + rationale addendum + status "LOCKED (revised 2026-08-24)"; new A7 revision note under the anchors table; §6 bullet "never truncated"; §12 row 24 + footnote; header Revisions line updated — all marked owner permission 2026-08-24.
+- Validated tasks 01/02 work in tree (no-truncation `select_documents`, removed `max_context_chars`/env/knob, mock tail-echo, E2E suite) — no defects found; `rg "max_context" app/ tests/ .env.example README.md` → 0 matches.
+- `uv run pytest` → green (333 passed)
+- `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 99% (>90% gate)
+- `uv run pytest tests/e2e/test_whole_document_context.py -v --no-cov` → 3 passed in isolation; regressions `test_chat_rag.py` + `test_honest_deflection.py` → 6 passed
+- `uv run ruff check . && uv run pyright` → "All checks passed!" / 0 errors
+- Moved phase dir to `complete/`; one `--no-gpg-sign` commit `1e6ae36` per the 00_phase.md block.
+- Notable: commit also records phase 23's post-commit phase-dir move (stale tracked deletions — phase-23 precedent of sweeping the prior phase's move); owner's new TODO.md item ("global tuning") deliberately left uncommitted for a future conversion.
+- Next pending task: none — `.agents/phases/todo/` is empty (TODO.md holds one new owner item awaiting a phase conversion).
@@ -0,0 +1,46 @@
+........................................................................ [ 21%]
+........................................................................ [ 43%]
+........................................................................ [ 64%]
+........................................................................ [ 86%]
+.............................................                            [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               55      0   100%
+app/core/__init__.py         0      0   100%
+app/core/auth.py            20      0   100%
+app/core/debugging.py       29      2    93%
+app/core/logging.py         13      0   100%
+app/db.py                   21      0   100%
+app/main.py                 36      0   100%
+app/models.py               46      0   100%
+app/rag/__init__.py          0      0   100%
+app/rag/chunker.py         206      4    98%
+app/rag/importer.py        150      5    97%
+app/rag/llm.py             105      0   100%
+app/rag/prompts.py          44      0   100%
+app/rag/retriever.py        93      3    97%
+app/rag/suggestions.py      27      0   100%
+app/schemas.py              62      0   100%
+--------------------------------------------
+TOTAL                     1099     14    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK