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/36_summary_in_viewer/36_summary_in_viewer__00_phase.a1.err
View File
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__00_phase.a1.md
+28
View File
@@ -0,0 +1,28 @@
All gates verified green. Final report:
## Phase 36 — Summary in Viewer: final verification pass (no code changes needed)
**Verified implementation** (all committed in `9efffcb`, unsigned ✓):
- `DocContent.summary: str | None` (schemas.py) + `GET /api/documents/content` returns `summary=doc.summary` — still public/stateless (phase-16 soft rule intact)
- Shared `renderDocument` draws labeled `.doc-summary` section (aria-label + `<h2>`, `textContent` — XSS-safe) above content on both surfaces, only when summary non-empty
- Theme-matched styles: brand-ink `#a5b4fc` on surface ≈8.7:1, ink ≈14.5:1 (≥4.5:1); no CDN refs in frontend
**Test / lint / coverage results:**
- `uv run pytest` → 596 passed
- `uv run pytest --cov=app --cov-report=term-missing` → **99%** (>90% gate; `app/api/docs.py` 100%)
- `uv run pytest tests/e2e/test_summary_in_viewer.py -v --no-cov` → 4 passed, in isolation
- Regressions, each isolated: `test_document_viewer` 7, `test_document_summaries` 2, `test_document_back_navigation` 3, `test_chat_rag` 3, `test_smoke` 3 — all passed
- `uv run ruff check . && uv run pyright` → All checks passed / 0 errors
**Completion criteria:**
- API returns `summary` (string/null), anonymous 200 unchanged — ✅ (integration tests assert verbatim, `null` for markdown, anonymous 200)
- Panel above original on both surfaces, original fully visible — ✅ (E2E: digest + sentinel `RESE-SUMMARY-SENTINEL-7f3a` together, page and modal agree)
- Markdown doc: no empty panel — ✅ (E2E control)
- Full test/coverage/E2E gates — ✅ (above)
- Lint/types clean — ✅
- UI Structure Check (labeled section, contrast, no CDN) — ✅
- One `--no-gpg-sign` commit; phase dir move — ✅ commit exists (task files already in `complete/`; `00_phase.md` move left to harness per protocol)
**Notable:** working-tree `M TODO.md` (new "Tuning button" item) and untracked `NOTES.md` (agent-tool ideas) are user/harness content — left untouched, not part of this phase.
**Next pending phase:** `37_agent_document_tools`
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__00_phase.a1.validate
+56
View File
@@ -0,0 +1,56 @@
........................................................................ [ 12%]
........................................................................ [ 24%]
........................................................................ [ 36%]
........................................................................ [ 48%]
........................................................................ [ 60%]
........................................................................ [ 72%]
........................................................................ [ 84%]
........................................................................ [ 96%]
.................... [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/git_sources.py 44 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 72 0 100%
app/config.py 64 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 42 0 100%
app/models.py 58 0 100%
app/rag/__init__.py 0 0 100%
app/rag/chunker.py 206 4 98%
app/rag/git_sources.py 11 0 100%
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 82 0 100%
--------------------------------------------
TOTAL 1534 12 99%
coverage gate: app/ 99% (>90%) OK
All checks passed!
0 errors, 0 warnings, 0 informations
validation OK
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__01_content_api_summary_field.a1.err
View File
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__01_content_api_summary_field.a1.md
+14
View File
@@ -0,0 +1,14 @@
All green. Task 01 is complete — commit belongs to task 03 (phase-level gate), so no commit here.
**Report — Task 01 (36_summary_in_viewer): content endpoint returns the summary**
- `app/schemas.py`: `DocContent` gains nullable `summary` (after `format`, before `content`), docstring mirroring `Document.summary`
- `app/api/docs.py`: `get_document_content` returns `summary=doc.summary`; endpoint stays public/stateless, no other change
- `tests/integration/test_document_content.py`: `_seed_doc` takes `summary`; new tests — summarized non-markdown doc returns summary verbatim (anonymous 200), markdown doc returns `"summary": null` (anonymous 200); existing field-set assertion extended to include `summary`
- Fixed 2 pre-existing tests that asserted the exact old field set (now updated to the new contract): `tests/unit/test_document_viewer.py::test_content_known_pair_maps_to_doc_content`, `tests/integration/test_auth_api.py::test_anonymous_document_content_stays_public`
- `uv run pytest --cov=app --cov-report=term`: **596 passed**, `app/` coverage **99%** (>90%)
- `uv run pytest tests/integration/test_document_content.py -v --no-cov`: 6 passed
- `uv run ruff check .`: all checks passed; `uv run pyright`: 0 errors
- No deviations: no auth/shape change beyond the added nullable field; frontend untouched (task 02)
**Next pending task:** `.agents/phases/todo/36_summary_in_viewer/02_viewer_summary_panel.md`
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__01_content_api_summary_field.a1.validate
+56
View File
@@ -0,0 +1,56 @@
........................................................................ [ 12%]
........................................................................ [ 24%]
........................................................................ [ 36%]
........................................................................ [ 48%]
........................................................................ [ 60%]
........................................................................ [ 72%]
........................................................................ [ 84%]
........................................................................ [ 96%]
.................... [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/git_sources.py 44 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 72 0 100%
app/config.py 64 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 42 0 100%
app/models.py 58 0 100%
app/rag/__init__.py 0 0 100%
app/rag/chunker.py 206 4 98%
app/rag/git_sources.py 11 0 100%
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 82 0 100%
--------------------------------------------
TOTAL 1534 12 99%
coverage gate: app/ 99% (>90%) OK
All checks passed!
0 errors, 0 warnings, 0 informations
validation OK
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__02_viewer_summary_panel.a1.err
View File
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__02_viewer_summary_panel.a1.md
+18
View File
@@ -0,0 +1,18 @@
Task 02 complete. All gates green.
**Implemented**
- `frontend/assets/document.js` — shared `renderDocument` core now draws the labeled `.doc-summary` section (h2 "Summary" + `<p>` via `textContent`, `aria-label="Summary"`) above the original content whenever `doc.summary` is non-empty; `null`/empty/whitespace renders nothing → markdown docs and fail-soft rows byte-for-byte unchanged. File-header + doc comments updated (renderer now owns the optional panel).
- `frontend/assets/styles.css` — phase-08-palette panel: surface card with 3px brand left border, `var(--radius)`, small-caps brand-ink label (`#a5b4fc` on surface ≈8.7:1), ink body (≈14.5:1); mobile padding tweak; no animation (nothing for reduced-motion to still).
- Panel width matches its content: full-width for raw docs (like `.doc-raw`), ≤46rem centered for md (like `.doc-md`) via `.doc-summary:has(+ .doc-md)` (degrades to full-width in engines without `:has()`).
- `document-modal.js`, `markdown.js`, page scripts untouched — the modal gets the panel for free through the shared core (phase-26 principle).
**Test / lint results**
- `uv run pytest --cov=app --cov-report=term-missing` → 596 passed, TOTAL **99%** (>90% gate)
- `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors
- Node behavioral harness (stub DOM, real `renderDocument`+`renderMarkdown`): 16/16 — panel first in DOM for md+raw with summary, full original content after it, no panel for null/`""`/whitespace, zero `innerHTML` on the panel, meta row's 5 badges unchanged.
**Decisions / deviations**
- Used the 3px brand left-border look (one of the two task options, kept simple); `:has()` is the only way to hit both width contracts with the task's prescribed single-class JS — graceful fallback otherwise.
- No commit made (task 03 owns the phase commit); task/phase files untouched.
**Next pending task:** `.agents/phases/todo/36_summary_in_viewer/03_e2e_and_regression.md` (story E2E suite + regressions + full gate + commit).
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__02_viewer_summary_panel.a1.validate
+56
View File
@@ -0,0 +1,56 @@
........................................................................ [ 12%]
........................................................................ [ 24%]
........................................................................ [ 36%]
........................................................................ [ 48%]
........................................................................ [ 60%]
........................................................................ [ 72%]
........................................................................ [ 84%]
........................................................................ [ 96%]
.................... [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/git_sources.py 44 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 72 0 100%
app/config.py 64 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 42 0 100%
app/models.py 58 0 100%
app/rag/__init__.py 0 0 100%
app/rag/chunker.py 206 4 98%
app/rag/git_sources.py 11 0 100%
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 82 0 100%
--------------------------------------------
TOTAL 1534 12 99%
coverage gate: app/ 99% (>90%) OK
All checks passed!
0 errors, 0 warnings, 0 informations
validation OK
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__03_e2e_and_regression.a1.err
View File
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__03_e2e_and_regression.a1.md
+16
View File
@@ -0,0 +1,16 @@
Phase 36 complete. Report:
**Implemented**
- `tests/e2e/test_summary_in_viewer.py` (new, 4 tests, story gate): full page shows labeled `.doc-summary` panel (deterministic mock digest + pointer line) above the full original (tail sentinel `RESE-SUMMARY-SENTINEL-7f3a` in `pre.doc-raw`, panel first child, phase-08 colors, width matches content); modal from admin Sources row shows the same panel + sentinel, and "Full page" (`target=_blank` → popup) agrees on the dedicated page; markdown control doc → zero `.doc-summary` on both surfaces; anonymous `context.request` API checks: yaml `summary` = expected string, md `null`, both 200 (soft rule intact).
- Reused `test_document_summaries.py` machinery (fixture KB import, thread runner, `_expected_summary` digest helper).
**Gates (all green)**
- `uv run pytest tests/e2e/test_summary_in_viewer.py -v --no-cov` → 4 passed (isolation)
- Regressions in isolation: `test_document_viewer.py` 7, `test_document_summaries.py` 2, `test_document_back_navigation.py` 3, `test_chat_rag.py` 3, `test_smoke.py` 3 — all passed
- `uv run pytest --cov=app --cov-report=term-missing` → 596 passed, **99%** coverage
- `uv run ruff check . && uv run pyright` → clean
**Decisions / deviations**
- Commit `9efffcb` (8 files, `--no-gpg-sign`) covers tasks 01–03 code; unrelated TODO.md/NOTES.md left unstaged. Phase dir NOT moved to `complete/` — harness owns that move per protocol.
**Next pending task:** `37_agent_document_tools/01_probe_tool_calling.md`
.agents/reports/36_summary_in_viewer/36_summary_in_viewer__03_e2e_and_regression.a1.validate
+56
View File
@@ -0,0 +1,56 @@
........................................................................ [ 12%]
........................................................................ [ 24%]
........................................................................ [ 36%]
........................................................................ [ 48%]
........................................................................ [ 60%]
........................................................................ [ 72%]
........................................................................ [ 84%]
........................................................................ [ 96%]
.................... [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/git_sources.py 44 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 72 0 100%
app/config.py 64 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 42 0 100%
app/models.py 58 0 100%
app/rag/__init__.py 0 0 100%
app/rag/chunker.py 206 4 98%
app/rag/git_sources.py 11 0 100%
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 82 0 100%
--------------------------------------------
TOTAL 1534 12 99%
coverage gate: app/ 99% (>90%) OK
All checks passed!
0 errors, 0 warnings, 0 informations
validation OK