brain-of-reese

257 Commits 1 Branch 0 Tags

3 Commits

Include renames

Author	SHA1	Message	Date
ducoterra	2ac37455f0	phase: 167_api_payload_diet Build and Push Containers / build-and-push-app (push) Successful in 1m45s Details Build and Push Containers / build-and-push-db (push) Successful in 14s Details All gates green. Final report: Verified (phase 167 final pass — all 6 tasks already in `complete/`) - Live re-measure of the headline criterion on the 1,000-doc live-replica corpus (restored `data/bor_live_kb_replica.dump.sql` into a scratch DB `bor_audit`, alembic 0011→0027, dropped after; the shared dev DB was never touched): `GET /api/docs/tree` default depth=1 = 8,474 identity → 1,128 B with `Content-Encoding: gzip` (< 40 KB bar; ~2 MB defect fixed), repeat load 304 / 0 bytes; depth=8 265,147→23,515; node drill 20,844→1,065; `/api/docs` 246,366→45,104; `/api/documents/content` 892,124→60,776 (`LOOK`, accepted-with-why). Reproduces `AUDIT.md` to within 1 byte. - Transport contracts proven live: `POST /api/chat` no `Content-Encoding` + frames arriving live + budget line `… enc=identity duration_ms=7380 stream=1`; HTML still `no-cache` with the `?v=` rewrite (and gzipped); A20 headers on 200 and 304; ETag identical across identity/gzip; `depth=0\|9\|abc`→422; anonymous tree/node→403; unknown folder/source→404 `unknown node`. Gates (all 100% green) - `uv run pytest` → 3980 passed; `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 99% (`compression.py`, `http_cache.py`, `response_budget.py` 100%; `api/docs.py` 99%, one defensive dedupe line). - `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors. - Phase + regression E2E in isolation (`--junitxml`, exit codes): `test_kb_tree_lazy_load` 11, `test_kb_tree` 8, `test_kb_tree_nav` 4, `test_navbar_refresh` 7, `test_document_dates` 6, `test_git_source_dates` 4, `test_sync_summary_visibility` 3, `test_table_ux_polish` 6, `test_sources_midstream_bug` 6, `test_ls_tree_drilldown` 3, `test_smoke` 3 — 0 failures/errors (the earlier `-q -q` run had simply suppressed pytest's summary line). Documentation — README.md + AGENTS.md reviewed in full (1,436 / 80 lines): - Fixed (pre-existing, phase-167-exposed): README Caching & deploys claimed "One Starlette middleware (`app/core/caching.py`) applies the rule" while the section now describes three transport layers → rewritten to name caching/compression/http_cache, the real outermost→innermost order, and why `bytes=` is uncompressed. - AGENTS.md rule 5 (UI Structure Check) gained the phase-167 clause: a lazily-drilled level keeps the current level rendered, its in-flight `role="status"` / `role="alert"`+Retry row lives in the same bounded scroll panel, and stat cards read server `totals` (never a walk of a depth-limited tree). - Cross-checked and consistent: every `BOR_` in `.env.example` is in the README table, every `Settings` field is documented, all 15 README-cited API routes exist in the app, no stale "one fetch / drill client-side" claim remains anywhere. Notable decisions / deviations* - `compression.py` adds a documented `_RebufferSmallResponses` seam beyond the D1 sketch (the caching layer's `BaseHTTPMiddleware` re-framing otherwise defeats Starlette's `minimum_size` exemption and inflates tiny responses) — integration-pinned, math still Starlette's. - A node-route 404 = vanished folder → honest reset to top level (per `00_phase.md` D4/D6), not task-06's "alert + Retry"; 500 shows alert+Retry with the level preserved — both pinned, nothing weakened. - Retrieval battery not measurable (shared E2E DB holds no corpus), but `git diff --name-only -- app/rag` is empty, so retrieval is unchanged by construction. `AUDIT.md` left byte-identical (it lives under `todo/`, off-limits to this pass); no git index/history commands run. Next pending phase: none — `167_api_payload_diet` is the only entry in `.agents/phases/todo/`; the harness moves it to `complete/` and commits.	2026-10-08 21:23:49 -04:00
ducoterra	8d70aa946c	docs(phases): close two gaps in phase 167 - the date-pin tree consumers and drifted line anchors Audit of the written phase found the depth=1 default was specified without naming two of its nine consumers, both of which walk the tree without a depth parameter and assert phase-106 D9 dates: - tests/integration/test_docs_api_dates.py (reaches a -> a/b -> deeper) - tests/e2e/test_git_source_dates.py (_find_file recurses by design) Task 02 gains item 9 (both migrate by requesting ?depth=8 explicitly with every assertion intact, plus the truncation-proof pin that a truncated folder's updated_at still equals the deep max), task 06's isolation list names the E2E suite, and the overview's D2 now carries the full nine-file consumer list. Also corrected the Context anchors: build_kb_tree is L780 (not 781) and _subtree_max is L760 (not 746). LLM-Generated: true	2026-10-07 19:49:06 -04:00
ducoterra	dcb1062b83	docs(phases): convert TODO L3-L5 into phases 165-167 (prose wrap, no empty answer box, API payload diet) Three owner-reported defects become executable phases; TODO.md is cleared once the roadmap is written (Protocol B append, PLAN.md/AGENTS.md untouched). - 165_prose_word_wrap (TODO L3): image descriptions and .txt bodies render as a wrapping .doc-prose block instead of <pre class="doc-raw"> (page + modal via the one renderDocument core). Code and code-ish formats keep horizontal scroll - phase 116 locked A1 survives; extracted PDF text stays raw and the deferral is recorded as an owner call, not an oversight. - 166_hide_empty_answer_bubble (TODO L4): .msg .bubble:empty { display: none }. CSS-only, so the phase-158/161 "reasoning container inserts before the bubble" anchor and its unit pins stay untouched; the box returns at the first delta, and the shared/restore empty-answer corners take the same path. - 167_api_payload_diet (TODO L5): selective pure-ASGI gzip (SSE /api/chat skipped by exact path), a depth-limited KB tree with server-side totals + truncated nodes whose recursive updated_at comes from a new aggregate map, a GET /api/docs/tree/node drill route, content-hash weak ETag/304 on the catalogue reads (NOT sources_meta - bumping it would mark saved chats stale), the lazy client drill, and a /api/* byte-budget log line plus scripts/api_payload_audit.py whose measured numbers land in AUDIT.md. Phase 97's "one fetch, drill client-side" contract is deliberately superseded (locked A3); phase 116 A1, phase 158/161 anchors and A19/A20 middleware order are explicitly preserved. LLM-Generated: true	2026-10-07 19:42:34 -04:00

Author

SHA1

Message

Date

ducoterra

2ac37455f0

phase: 167_api_payload_diet

Build and Push Containers / build-and-push-app (push) Successful in 1m45s

Details

Build and Push Containers / build-and-push-db (push) Successful in 14s

Details

All gates green. Final report:

**Verified (phase 167 final pass — all 6 tasks already in `complete/`)**
- Live re-measure of the headline criterion on the **1,000-doc live-replica corpus** (restored `data/bor_live_kb_replica.dump.sql` into a scratch DB `bor_audit`, alembic 0011→0027, dropped after; the shared dev DB was never touched): `GET /api/docs/tree` default depth=1 = **8,474 identity → 1,128 B with `Content-Encoding: gzip`** (< 40 KB bar; ~2 MB defect fixed), repeat load **304 / 0 bytes**; depth=8 265,147→23,515; node drill 20,844→1,065; `/api/docs` 246,366→45,104; `/api/documents/content` 892,124→60,776 (`LOOK`, accepted-with-why). Reproduces `AUDIT.md` to within 1 byte.
- Transport contracts proven live: `POST /api/chat` **no** `Content-Encoding` + frames arriving live + budget line `… enc=identity duration_ms=7380 stream=1`; HTML still `no-cache` with the `?v=` rewrite (and gzipped); A20 headers on 200 **and** 304; ETag identical across identity/gzip; `depth=0|9|abc`→422; anonymous tree/node→403; unknown folder/source→404 `unknown node`.

**Gates (all 100% green)**
- `uv run pytest` → **3980 passed**; `uv run pytest --cov=app --cov-report=term-missing` → **TOTAL 99%** (`compression.py`, `http_cache.py`, `response_budget.py` 100%; `api/docs.py` 99%, one defensive dedupe line).
- `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors.
- Phase + regression E2E **in isolation** (`--junitxml`, exit codes): `test_kb_tree_lazy_load` 11, `test_kb_tree` 8, `test_kb_tree_nav` 4, `test_navbar_refresh` 7, `test_document_dates` 6, `test_git_source_dates` 4, `test_sync_summary_visibility` 3, `test_table_ux_polish` 6, `test_sources_midstream_bug` 6, `test_ls_tree_drilldown` 3, `test_smoke` 3 — **0 failures/errors** (the earlier `-q -q` run had simply suppressed pytest's summary line).

**Documentation** — README.md + AGENTS.md reviewed in full (1,436 / 80 lines):
- Fixed (pre-existing, phase-167-exposed): README *Caching & deploys* claimed "One Starlette middleware (`app/core/caching.py`) applies the rule" while the section now describes three transport layers → rewritten to name caching/compression/http_cache, the real outermost→innermost order, and why `bytes=` is uncompressed.
- AGENTS.md rule 5 (UI Structure Check) gained the phase-167 clause: a lazily-drilled level keeps the current level rendered, its in-flight `role="status"` / `role="alert"`+Retry row lives in the same bounded scroll panel, and stat cards read server `totals` (never a walk of a depth-limited tree).
- Cross-checked and consistent: every `BOR_*` in `.env.example` is in the README table, every `Settings` field is documented, all 15 README-cited API routes exist in the app, no stale "one fetch / drill client-side" claim remains anywhere.

**Notable decisions / deviations**
- `compression.py` adds a documented `_RebufferSmallResponses` seam beyond the D1 sketch (the caching layer's `BaseHTTPMiddleware` re-framing otherwise defeats Starlette's `minimum_size` exemption and inflates tiny responses) — integration-pinned, math still Starlette's.
- A node-route **404 = vanished folder → honest reset to top level** (per `00_phase.md` D4/D6), not task-06's "alert + Retry"; 500 shows alert+Retry with the level preserved — both pinned, nothing weakened.
- Retrieval battery not measurable (shared E2E DB holds no corpus), but `git diff --name-only -- app/rag` is empty, so retrieval is unchanged by construction. `AUDIT.md` left byte-identical (it lives under `todo/`, off-limits to this pass); no git index/history commands run.

**Next pending phase:** none — `167_api_payload_diet` is the only entry in `.agents/phases/todo/`; the harness moves it to `complete/` and commits.

2026-10-08 21:23:49 -04:00

ducoterra

8d70aa946c

docs(phases): close two gaps in phase 167 - the date-pin tree consumers and drifted line anchors

Audit of the written phase found the depth=1 default was specified without
naming two of its nine consumers, both of which walk the tree without a
depth parameter and assert phase-106 D9 dates:

- tests/integration/test_docs_api_dates.py (reaches a -> a/b -> deeper)
- tests/e2e/test_git_source_dates.py (_find_file recurses by design)

Task 02 gains item 9 (both migrate by requesting ?depth=8 explicitly with
every assertion intact, plus the truncation-proof pin that a truncated
folder's updated_at still equals the deep max), task 06's isolation list
names the E2E suite, and the overview's D2 now carries the full nine-file
consumer list. Also corrected the Context anchors: build_kb_tree is L780
(not 781) and _subtree_max is L760 (not 746).

LLM-Generated: true

2026-10-07 19:49:06 -04:00

ducoterra

dcb1062b83

docs(phases): convert TODO L3-L5 into phases 165-167 (prose wrap, no empty answer box, API payload diet)

Three owner-reported defects become executable phases; TODO.md is cleared
once the roadmap is written (Protocol B append, PLAN.md/AGENTS.md untouched).

- 165_prose_word_wrap (TODO L3): image descriptions and .txt bodies render as
  a wrapping .doc-prose block instead of <pre class="doc-raw"> (page + modal via
  the one renderDocument core). Code and code-ish formats keep horizontal scroll
  - phase 116 locked A1 survives; extracted PDF text stays raw and the deferral
  is recorded as an owner call, not an oversight.
- 166_hide_empty_answer_bubble (TODO L4): .msg .bubble:empty { display: none }.
  CSS-only, so the phase-158/161 "reasoning container inserts before the bubble"
  anchor and its unit pins stay untouched; the box returns at the first delta,
  and the shared/restore empty-answer corners take the same path.
- 167_api_payload_diet (TODO L5): selective pure-ASGI gzip (SSE /api/chat skipped
  by exact path), a depth-limited KB tree with server-side totals + truncated
  nodes whose recursive updated_at comes from a new aggregate map, a
  GET /api/docs/tree/node drill route, content-hash weak ETag/304 on the catalogue
  reads (NOT sources_meta - bumping it would mark saved chats stale), the lazy
  client drill, and a /api/* byte-budget log line plus scripts/api_payload_audit.py
  whose measured numbers land in AUDIT.md.

Phase 97's "one fetch, drill client-side" contract is deliberately superseded
(locked A3); phase 116 A1, phase 158/161 anchors and A19/A20 middleware order are
explicitly preserved.

LLM-Generated: true

2026-10-07 19:42:34 -04:00