Experimental/brain-of-reese
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(agents): migrate .agent/ planning tree to .agents/

Browse Source 
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.
This commit is contained in:
ducoterra
2026-09-05 10:57:07 -04:00
parent 766702c750
commit dbf2af26c6
1118 changed files with 664 additions and 664 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__00_phase.a1.err
View File
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__00_phase.a1.md
+20
View File
@@ -0,0 +1,20 @@
Final verification pass complete — phase 57 was already fully implemented (commit `140b97e`); all gates verified green with no defects found.
**Phase 57 — Edit + Re-embed Document Summaries: VERIFIED (no changes needed)**
- `PATCH /api/documents/summary` (admin, embed-before-write, 503 on LLM failure) — verified in `app/api/docs.py`
- Admin-only edit UI (page + modal), live-region status, `textContent` render contract — verified in `frontend/assets/document.js`
- All 6 PATCH integration cases present (update/re-embed, clear, markdown-create, 404, 403, 503-DB-untouched)
Test / lint / coverage results:
- `uv run pytest --cov=app --cov-report=term-missing` → all passed, exit 0, **TOTAL 99%** (2269 stmts / 12 miss)
- `uv run pytest tests/e2e/test_edit_summaries.py -v --no-cov` → **4 passed** (isolated, DB up)
- Regression E2E isolated: `test_document_summaries` **2 passed**, `test_document_viewer` **7 passed**, `test_cache_busting` **4 passed**
- `uv run ruff check . && uv run pyright` → clean (0 errors)
Completion criteria:
- Update/re-embed (count unchanged): ✅ | Clear → NULL + chunk deleted: ✅
- Anonymous 403, no button, byte-identical viewer: ✅ | Button on page+modal, prefill, live region, cancel: ✅
- pytest + coverage >90%: ✅ (99%) | story E2E isolated: ✅ | regression E2Es: ✅ | ruff+pyright: ✅
- Atomic commit: ✅ `140b97e feat(kb): edit + re-embed document summaries from the viewer (admin)`; working tree clean. Phase-dir move left to harness per rules.
Next pending phase: **58_wide_desktop_column**
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__00_phase.a1.validate
+68
View File
@@ -0,0 +1,68 @@
........................................................................ [ 6%]
........................................................................ [ 13%]
........................................................................ [ 19%]
........................................................................ [ 26%]
........................................................................ [ 32%]
........................................................................ [ 39%]
........................................................................ [ 46%]
........................................................................ [ 52%]
........................................................................ [ 59%]
........................................................................ [ 65%]
........................................................................ [ 72%]
........................................................................ [ 78%]
........................................................................ [ 85%]
........................................................................ [ 92%]
........................................................................ [ 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 131 0 100%
app/api/chats.py 110 0 100%
app/api/config.py 7 0 100%
app/api/docs.py 50 0 100%
app/api/git_sources.py 143 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 89 0 100%
app/config.py 80 0 100%
app/core/__init__.py 0 0 100%
app/core/auth.py 20 0 100%
app/core/caching.py 108 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 50 0 100%
app/models.py 74 0 100%
app/rag/__init__.py 0 0 100%
app/rag/agent.py 78 0 100%
app/rag/archive_upload.py 128 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 189 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/sources_meta.py 16 0 100%
app/rag/suggestions.py 27 0 100%
app/rag/summarizer.py 24 0 100%
app/schemas.py 176 0 100%
-----------------------------------------------
TOTAL 2269 12 99%
coverage gate: app/ 99% (>90%) OK
All checks passed!
0 errors, 0 warnings, 0 informations
validation OK
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__01_update_summary_api.a1.err
View File
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__01_update_summary_api.a1.md
+17
View File
@@ -0,0 +1,17 @@
Task 01 complete and fully green.
**Implemented**
- `app/schemas.py`: `SummaryUpdate` (request) + `SummaryResult` (response, `summary: str | None`, post-change `chunks` count)
- `app/api/docs.py`: `PATCH /api/documents/summary` (async, `require_admin`-gated; viewer stays public per phase 16) — 404 `document not found` for unknown/traversal pairs; empty/whitespace text clears `documents.summary` (NULL) and deletes the `is_summary` chunk; non-empty text embeds **before** any mutation (one `embed` call), then upserts the position −1 `is_summary` chunk in place (creates it for markdown/fail-soft docs); `EmbeddingError` → 503 with `_sanitize_error` detail, DB untouched; module docstring route list extended
- `tests/integration/test_document_content.py`: 6 new cases (update + re-embed with content chunks byte-for-byte untouched, idempotent clear, markdown doc chunk creation, 404 incl. traversal, 403 anonymous, LLM-failure 503 with credentials masked and snapshots identical) — before/after chunk snapshots avoid pgvector float4 round-trip assumptions
**Results**
- `uv run pytest --cov=app --cov-report=term-missing` → 1081 passed, TOTAL 99% (docs.py 100%)
- `uv run pytest tests/integration/test_document_content.py -v --no-cov` → 12 passed
- `uv run pytest tests/e2e/test_document_viewer.py -v --no-cov` → 7 passed (sanity regression)
- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
**Decisions**
- 503 (not 502) for embed failure — matches the `git_sources.py` `ModelUnavailableError` house pattern; re-embed scope is the `is_summary` chunk only (D4), content chunks never touched.
**Next pending task:** `02_summary_edit_ui.md` (phase 57).
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__01_update_summary_api.a1.validate
+68
View File
@@ -0,0 +1,68 @@
........................................................................ [ 6%]
........................................................................ [ 13%]
........................................................................ [ 19%]
........................................................................ [ 26%]
........................................................................ [ 33%]
........................................................................ [ 39%]
........................................................................ [ 46%]
........................................................................ [ 53%]
........................................................................ [ 59%]
........................................................................ [ 66%]
........................................................................ [ 73%]
........................................................................ [ 79%]
........................................................................ [ 86%]
........................................................................ [ 93%]
........................................................................ [ 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 131 0 100%
app/api/chats.py 110 0 100%
app/api/config.py 7 0 100%
app/api/docs.py 50 0 100%
app/api/git_sources.py 143 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 89 0 100%
app/config.py 80 0 100%
app/core/__init__.py 0 0 100%
app/core/auth.py 20 0 100%
app/core/caching.py 108 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 50 0 100%
app/models.py 74 0 100%
app/rag/__init__.py 0 0 100%
app/rag/agent.py 78 0 100%
app/rag/archive_upload.py 128 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 189 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/sources_meta.py 16 0 100%
app/rag/suggestions.py 27 0 100%
app/rag/summarizer.py 24 0 100%
app/schemas.py 176 0 100%
-----------------------------------------------
TOTAL 2269 12 99%
coverage gate: app/ 99% (>90%) OK
All checks passed!
0 errors, 0 warnings, 0 informations
validation OK
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__02_summary_edit_ui.a1.err
View File
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__02_summary_edit_ui.a1.md
+18
View File
@@ -0,0 +1,18 @@
Everything is complete and verified. Final report:
**Phase 57 / Task 02 — summary edit UI (admin-only) — complete**
Implemented:
- `document.js`: `docAdminReady()` gate on the cached `fetchIsAdmin()` promise (no new whoami call site); `wireSummaryEdit()` — header row + `type=button` Edit, swap-in editor (prefilled textarea via `.value`, Save/Cancel, `role=status` live region), `PATCH /api/documents/summary {source, path, summary}`, textContent-only re-render, clear → panel removal, cancel restore, neutral failure copy (editor stays open), double-click guard in `finally`. Phase-36 base section untouched → anonymous viewer byte-for-byte identical.
- `styles.css`: the 5 task-named `.doc-summary-*` classes + 2 layout wrappers, phase-08 AA tokens, 8rem-min editor, 24px+ edit target, `[hidden]` override, global `:focus-visible`.
- `tests/unit/test_summary_edit_ui.py`: 13 house-style source pins (gate, construction, PATCH path/body, outcomes, guard, CSS palette).
Results:
- `uv run pytest --cov=app --cov-report=term` → 1094 passed, TOTAL 99% (>90% ✓)
- `uv run ruff check .` clean; `uv run pyright` → 0 errors
- Regression E2E in isolation: `test_document_summaries.py` + `test_document_viewer.py` + `test_cache_busting.py` + `test_summary_in_viewer.py` → 17 passed
- Throwaway Playwright smoke (deleted) verified the full admin flow on page **and** modal; it caught 2 real bugs, fixed: clear-confirmation removed before readable → 2s delayed panel removal; cancel-after-clear edge → empty-state guard in `closeEditor`.
Decisions: Edit button hides (not removed) while editing; structural `.doc-summary-head`/`-actions` wrappers added beyond the 5 named classes. Task 01's uncommitted changes left in the working tree (atomic commit is task 03).
Next pending task: `03_e2e_edit_summaries.md` (story E2E suite + regressions + atomic commit).
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__02_summary_edit_ui.a1.validate
+68
View File
@@ -0,0 +1,68 @@
........................................................................ [ 6%]
........................................................................ [ 13%]
........................................................................ [ 19%]
........................................................................ [ 26%]
........................................................................ [ 32%]
........................................................................ [ 39%]
........................................................................ [ 46%]
........................................................................ [ 52%]
........................................................................ [ 59%]
........................................................................ [ 65%]
........................................................................ [ 72%]
........................................................................ [ 78%]
........................................................................ [ 85%]
........................................................................ [ 92%]
........................................................................ [ 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 131 0 100%
app/api/chats.py 110 0 100%
app/api/config.py 7 0 100%
app/api/docs.py 50 0 100%
app/api/git_sources.py 143 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 89 0 100%
app/config.py 80 0 100%
app/core/__init__.py 0 0 100%
app/core/auth.py 20 0 100%
app/core/caching.py 108 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 50 0 100%
app/models.py 74 0 100%
app/rag/__init__.py 0 0 100%
app/rag/agent.py 78 0 100%
app/rag/archive_upload.py 128 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 189 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/sources_meta.py 16 0 100%
app/rag/suggestions.py 27 0 100%
app/rag/summarizer.py 24 0 100%
app/schemas.py 176 0 100%
-----------------------------------------------
TOTAL 2269 12 99%
coverage gate: app/ 99% (>90%) OK
All checks passed!
0 errors, 0 warnings, 0 informations
validation OK
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__03_e2e_edit_summaries.a1.err
View File
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__03_e2e_edit_summaries.a1.md
+16
View File
@@ -0,0 +1,16 @@
**Phase 57, Task 03 complete** — report:
**Implemented**
- Story-dedicated fixture `tests/fixtures/summary_edit_kb/quadlet/llamacpp.container` (A9 `.container`, mock `SUMMARY_MODE` 24-token digest as stored summary, last-line sentinel, token-diluted body)
- `tests/e2e/test_edit_summaries.py` (4 tests, Playwright, DB up, mock LLM): admin edit loop (Edit button → prefilled textarea → Save → live-region confirm; public API + DB verify new content, fresh non-NULL vector, unchanged count, raw chunks byte-identical); admin clear loop (panel leaves DOM, `summary` NULL, chunk count −1); anonymous pins (digest renders, no Edit button, phase-36 byte-for-byte section shape, 403 PATCH); modal-surface edit (both surfaces through one shared core)
- Committed the whole phase atomically: `140b97e feat(kb): edit + re-embed document summaries from the viewer (admin)` (`--no-gpg-sign`, 8 files: tasks 01–03 work; phase-dir move left to the harness per protocol)
**Test / lint / coverage**
- `uv run pytest tests/e2e/test_edit_summaries.py -v --no-cov` → 4 passed
- Regressions in isolation: `test_document_summaries.py` 2 passed, `test_document_viewer.py` 7 passed, `test_cache_busting.py` 4 passed, `test_summary_in_viewer.py` 4 passed (bonus)
- `uv run pytest --cov=app --cov-report=term-missing` → 1094 passed, TOTAL **99%** (>90%); `uv run pytest` → 1094 passed
- `uv run ruff check . && uv run pyright` → clean (fixed one pyright return-type error in the new suite)
**Decisions** — per-doc (not table-wide) count assertions + distinctive source with `finally` cleanup (phase-56 house pattern; no document DELETE endpoint exists); added the modal-surface test to satisfy the phase-level "page **and** modal" criterion beyond the task's page-only spec.
**Next pending task:** `todo/58_wide_desktop_column/01_wide_column_css.md`
.agents/reports/57_edit_document_summaries/57_edit_document_summaries__03_e2e_edit_summaries.a1.validate
+68
View File
@@ -0,0 +1,68 @@
........................................................................ [ 6%]
........................................................................ [ 13%]
........................................................................ [ 19%]
........................................................................ [ 26%]
........................................................................ [ 32%]
........................................................................ [ 39%]
........................................................................ [ 46%]
........................................................................ [ 52%]
........................................................................ [ 59%]
........................................................................ [ 65%]
........................................................................ [ 72%]
........................................................................ [ 78%]
........................................................................ [ 85%]
........................................................................ [ 92%]
........................................................................ [ 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 131 0 100%
app/api/chats.py 110 0 100%
app/api/config.py 7 0 100%
app/api/docs.py 50 0 100%
app/api/git_sources.py 143 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 89 0 100%
app/config.py 80 0 100%
app/core/__init__.py 0 0 100%
app/core/auth.py 20 0 100%
app/core/caching.py 108 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 50 0 100%
app/models.py 74 0 100%
app/rag/__init__.py 0 0 100%
app/rag/agent.py 78 0 100%
app/rag/archive_upload.py 128 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 189 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/sources_meta.py 16 0 100%
app/rag/suggestions.py 27 0 100%
app/rag/summarizer.py 24 0 100%
app/schemas.py 176 0 100%
-----------------------------------------------
TOTAL 2269 12 99%
coverage gate: app/ 99% (>90%) OK
All checks passed!
0 errors, 0 warnings, 0 informations
validation OK