phase: 97_kb_tree_catalog
All completion criteria verified — everything is green, no defects found. Final report: ## Phase 97 final verification pass — ALL GREEN **Verified (no code changes needed):** - `GET /api/docs/tree` (admin), `build_kb_tree` pure builder, `PATCH /api/folders/summary`, migration 0018 (`manually_edited`, head confirmed), generator skip/keep + `kept_manual` stat, RAG tree UI + edit affordance in `sources.js`/`index.html`/`styles.css` - `tests/e2e/test_kb_tree.py`: 8 passed — top level, drill source/folder, edit round-trip, clear, manual-desc-survives-sync, reload fallback, anonymous gate - Integration: tree shape/order/403/empty/indexed-only + PATCH update/create/root/clear/404/403/no-LLM + stat-walk equivalence (in `test_docs_api.py`); 3-field `folder_summaries=` import token preserved **Gates (exact commands):** - `uv run pytest --cov=app --cov-report=term-missing` → **2053 passed**, TOTAL coverage **99%** (>90% ✓) - `uv run ruff check . && uv run pyright` → **All checks passed / 0 errors** - `uv run pytest tests/e2e/test_kb_tree.py -v --no-cov` → **8 passed** in isolation - 30 story/RAG-view E2E suites run **one per process**: all passed, incl. `test_ls_tree_drilldown` (agent `ls` byte-identical ✓), `test_import_documents`, `test_edit_summaries`, `test_admin_auth`, `test_kb_overview` **Completion criteria:** tree view ✓ · edit round-trip + clear ✓ · manual persists/clear resets ✓ · `ls` unchanged ✓ · pytest/coverage/lint ✓ · E2E isolation ✓ · commit — left to harness per protocol (working tree untouched, `git add/commit` not run) **Deviations:** none. **Next pending phase:** none — `todo/` contains only 97 (96 already committed).
This commit is contained in:
@@ -441,7 +441,7 @@ def test_generate_happy_path_upserts_every_candidate_folder(
|
||||
llm = _FakeLLM()
|
||||
with caplog.at_level(logging.INFO, logger="app.rag.folder_summaries"):
|
||||
stats = asyncio.run(generate_folder_summaries(db, llm))
|
||||
assert stats == {"generated": 3, "failed": 0, "pruned": 0}
|
||||
assert stats == {"generated": 3, "failed": 0, "pruned": 0, "kept_manual": 0}
|
||||
assert llm.calls == 3, "one lite call per candidate folder (the solo folder: none)"
|
||||
|
||||
stored = _rows(db)
|
||||
@@ -472,7 +472,8 @@ def test_generate_happy_path_upserts_every_candidate_folder(
|
||||
assert "root.md — Root" not in a_prompt
|
||||
|
||||
assert (
|
||||
"folder_summaries: generated=3 failed=0 pruned=0" in caplog.text
|
||||
"folder_summaries: generated=3 failed=0 pruned=0 kept_manual=0"
|
||||
in caplog.text
|
||||
), "the stats line must be greppable (PLAN §9 ample logging)"
|
||||
|
||||
|
||||
@@ -488,7 +489,7 @@ def test_generate_per_folder_fail_soft_keeps_previous_and_lands_others(
|
||||
llm = _FakeLLM(fail_folders=("FSU/a/b",))
|
||||
with caplog.at_level(logging.ERROR, logger="app.rag.folder_summaries"):
|
||||
stats = asyncio.run(generate_folder_summaries(db, llm))
|
||||
assert stats == {"generated": 2, "failed": 1, "pruned": 0}
|
||||
assert stats == {"generated": 2, "failed": 1, "pruned": 0, "kept_manual": 0}
|
||||
assert llm.calls == 3 # the failing folder was attempted too
|
||||
|
||||
stored = _rows(db)
|
||||
@@ -547,7 +548,7 @@ def test_generate_skip_is_a_full_noop(db: Session, clean_tables) -> None:
|
||||
db.commit()
|
||||
llm = _FakeLLM()
|
||||
stats = asyncio.run(generate_folder_summaries(db, llm, skip=True))
|
||||
assert stats == {"generated": 0, "failed": 0, "pruned": 0}
|
||||
assert stats == {"generated": 0, "failed": 0, "pruned": 0, "kept_manual": 0}
|
||||
assert llm.calls == 0
|
||||
assert _rows(db) == {("FSU", ""): "existing"}
|
||||
|
||||
@@ -560,7 +561,7 @@ def test_generate_empty_kb_prunes_every_row(db: Session, clean_tables) -> None:
|
||||
db.commit()
|
||||
llm = _FakeLLM()
|
||||
stats = asyncio.run(generate_folder_summaries(db, llm))
|
||||
assert stats == {"generated": 0, "failed": 0, "pruned": 2}
|
||||
assert stats == {"generated": 0, "failed": 0, "pruned": 2, "kept_manual": 0}
|
||||
assert llm.calls == 0
|
||||
assert _rows(db) == {}
|
||||
|
||||
@@ -613,6 +614,113 @@ def test_generate_only_flushes_caller_commits(db: Session, clean_tables) -> None
|
||||
assert MIN_DOCS_PER_FOLDER == 2 # the ≥ 2 scope rule, pinned by name
|
||||
|
||||
|
||||
# ---------- manually_edited (phase 97, task 01) ----------
|
||||
|
||||
|
||||
def test_manual_row_survives_regeneration(
|
||||
db: Session, clean_tables, caplog: pytest.LogCaptureFixture
|
||||
) -> None:
|
||||
"""An owner-edited row is SKIPPED on regeneration (phase 97, task
|
||||
01): the fake LLM is never called for it (no ``lite`` burn on owner
|
||||
text — not even a prompt is built), its text AND ``updated_at``
|
||||
stay byte-identical, ``kept_manual`` counts it, the flag is never
|
||||
cleared, and the 4-field log line carries it (PLAN §9)."""
|
||||
_seed_catalogue(db)
|
||||
manual_text = "Owner's own words about a/."
|
||||
db.add(
|
||||
FolderSummary(
|
||||
source="FSU", folder_path="a", summary=manual_text,
|
||||
manually_edited=True,
|
||||
)
|
||||
)
|
||||
db.commit()
|
||||
stamp_before = _updated_at(db, "FSU", "a")
|
||||
assert stamp_before is not None
|
||||
|
||||
llm = _FakeLLM()
|
||||
with caplog.at_level(logging.INFO, logger="app.rag.folder_summaries"):
|
||||
stats = asyncio.run(generate_folder_summaries(db, llm))
|
||||
|
||||
assert stats == {"generated": 2, "failed": 0, "pruned": 0, "kept_manual": 1}
|
||||
assert llm.calls == 2, "the manual folder burns zero lite calls"
|
||||
assert [user.splitlines()[0] for _s, user in llm.requests] == [
|
||||
"Folder: FSU",
|
||||
"Folder: FSU/a/b",
|
||||
], "no prompt is ever built for the owner's folder"
|
||||
|
||||
stored = _rows(db)
|
||||
assert stored[("FSU", "a")] == manual_text, "the owner's text survives"
|
||||
assert _updated_at(db, "FSU", "a") == stamp_before, ("never re-stamped")
|
||||
assert stored[("FSU", "")] == REPLY and stored[("FSU", "a/b")] == REPLY, (
|
||||
"the non-manual candidates still regenerate (the flag is the difference)"
|
||||
)
|
||||
row = db.get(FolderSummary, ("FSU", "a"))
|
||||
assert row is not None and row.manually_edited is True, (
|
||||
"the generator never clears the flag"
|
||||
)
|
||||
assert (
|
||||
"folder_summaries: generated=2 failed=0 pruned=0 kept_manual=1"
|
||||
in caplog.text
|
||||
), "the 4-field stats line must be greppable (PLAN §9 ample logging)"
|
||||
|
||||
|
||||
def test_manual_row_survives_the_prune(db: Session, clean_tables) -> None:
|
||||
"""A manual row is NEVER pruned (phase 97, task 01): two folders
|
||||
drop below 2 documents — the MANUAL one keeps its row (owner
|
||||
content persists until cleared — the clear deletes it, so the next
|
||||
KB-changing sync regenerates an AI description) while the
|
||||
NON-manual twin loses its now-stale row; the flag is the only
|
||||
difference. A vanished folder's manual row is kept too, and its
|
||||
non-manual twin is pruned."""
|
||||
_add_doc(db, "FSU", "a/one.md", "One")
|
||||
_add_doc(db, "FSU", "a/two.md", "Two")
|
||||
_add_doc(db, "FSU", "b/one.md", "B One")
|
||||
_add_doc(db, "FSU", "b/two.md", "B Two")
|
||||
manual_text = "Owner's words about a/."
|
||||
db.add(
|
||||
FolderSummary(
|
||||
source="FSU", folder_path="a", summary=manual_text,
|
||||
manually_edited=True,
|
||||
)
|
||||
)
|
||||
db.add(FolderSummary(source="FSU", folder_path="b", summary="ai words"))
|
||||
db.add(
|
||||
FolderSummary(
|
||||
source="FSU", folder_path="gone/manual", summary="owner kept",
|
||||
manually_edited=True,
|
||||
)
|
||||
)
|
||||
db.add(FolderSummary(source="FSU", folder_path="gone/ai", summary="stale ai"))
|
||||
db.commit()
|
||||
|
||||
# a/ and b/ each drop below the minimum (2 -> 1 recursive doc).
|
||||
db.execute(
|
||||
text(
|
||||
"DELETE FROM documents WHERE source = 'FSU'"
|
||||
" AND path IN ('a/two.md', 'b/two.md')"
|
||||
)
|
||||
)
|
||||
db.commit()
|
||||
|
||||
llm = _FakeLLM()
|
||||
stats = asyncio.run(generate_folder_summaries(db, llm))
|
||||
|
||||
assert stats == {"generated": 1, "failed": 0, "pruned": 2, "kept_manual": 0}
|
||||
assert llm.calls == 1, "only the surviving candidate (the root) regenerates"
|
||||
stored = _rows(db)
|
||||
assert stored[("FSU", "a")] == manual_text, (
|
||||
"the manual row survives its folder dropping below the minimum"
|
||||
)
|
||||
assert ("FSU", "b") not in stored, (
|
||||
"the non-manual twin loses its stale row (the flag is the difference)"
|
||||
)
|
||||
assert stored[("FSU", "gone/manual")] == "owner kept", (
|
||||
"a vanished folder's manual row is kept — owner content until cleared"
|
||||
)
|
||||
assert ("FSU", "gone/ai") not in stored, ("the non-manual twin is pruned")
|
||||
assert stored[("FSU", "")] == REPLY # the root (2 docs) still regenerates
|
||||
|
||||
|
||||
# ---------- missing_folder_summaries (phase 96, task 02) ----------
|
||||
|
||||
|
||||
@@ -715,7 +823,7 @@ def test_only_missing_fills_exactly_the_missing_keys(
|
||||
|
||||
llm = _FakeLLM()
|
||||
stats = asyncio.run(generate_folder_summaries(db, llm, only_missing=True))
|
||||
assert stats == {"generated": 2, "failed": 0, "pruned": 0}
|
||||
assert stats == {"generated": 2, "failed": 0, "pruned": 0, "kept_manual": 0}
|
||||
assert llm.calls == 2, "one call per MISSING key — zero for present rows"
|
||||
assert [user.splitlines()[0] for _s, user in llm.requests] == [
|
||||
"Folder: FSU",
|
||||
@@ -738,7 +846,7 @@ def test_only_missing_no_gap_burns_zero_calls(db: Session, clean_tables) -> None
|
||||
stamps = {f: _updated_at(db, "FSU", f) for f in ("", "a", "a/b")}
|
||||
llm = _FakeLLM()
|
||||
stats = asyncio.run(generate_folder_summaries(db, llm, only_missing=True))
|
||||
assert stats == {"generated": 0, "failed": 0, "pruned": 0}
|
||||
assert stats == {"generated": 0, "failed": 0, "pruned": 0, "kept_manual": 0}
|
||||
assert llm.calls == 0, "zero-burn: no gap, no lite call"
|
||||
assert _rows(db) == before
|
||||
for folder, stamp in stamps.items():
|
||||
@@ -758,7 +866,7 @@ def test_only_missing_still_prunes_stale_rows(db: Session, clean_tables) -> None
|
||||
|
||||
llm = _FakeLLM()
|
||||
stats = asyncio.run(generate_folder_summaries(db, llm, only_missing=True))
|
||||
assert stats == {"generated": 2, "failed": 0, "pruned": 1}
|
||||
assert stats == {"generated": 2, "failed": 0, "pruned": 1, "kept_manual": 0}
|
||||
assert llm.calls == 2
|
||||
|
||||
stored = _rows(db)
|
||||
@@ -781,7 +889,7 @@ def test_only_missing_fail_soft_keeps_prior_and_lands_others(
|
||||
db.commit()
|
||||
llm = _FakeLLM(fail_folders=("FSU/a/b",))
|
||||
stats = asyncio.run(generate_folder_summaries(db, llm, only_missing=True))
|
||||
assert stats == {"generated": 1, "failed": 1, "pruned": 0}
|
||||
assert stats == {"generated": 1, "failed": 1, "pruned": 0, "kept_manual": 0}
|
||||
assert llm.calls == 2 # both missing folders were attempted
|
||||
|
||||
stored = _rows(db)
|
||||
|
||||
Reference in New Issue
Block a user