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).

tests/integration/test_sync_folder_summaries.py

@@ -275,7 +275,8 @@ def test_changed_import_generates_folder_rows(
     assert _updated_at(db, "MyDocs", "a") is not None
     # The stats log line (PLAN §9 ample logging).
     assert any(
-        "folder_summaries: generated=2 failed=0 pruned=0" in r.getMessage()
+        "folder_summaries: generated=2 failed=0 pruned=0 kept_manual=0"
+        in r.getMessage()
         for r in records
     )
 
@@ -470,6 +471,96 @@ def test_folder_lite_failure_keeps_previous_row_and_stays_green(
     assert root_stamp_after is not None and root_stamp_after > root_stamp_before
 
 
+def test_changed_import_never_overwrites_a_manual_row(
+    db: Session,
+    src: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Phase 97 (task 01): a manually-edited folder description survives
+    a KB-changing sync — the generator SKIPS it (zero
+    ``FOLDER_SUMMARY_MODE`` calls for it), the summary-line token
+    STAYS 3 fields (``folder_summaries=<generated>/<failed>/<pruned>``
+    — ``kept_manual`` is a stat, not a token), the manual row's text,
+    stamp, and flag are untouched, and the other folders regenerate
+    (the ``kept_manual`` stat lands on the generator's log line)."""
+    # First sync: full generation — root + a/ (b/ holds 1 doc: none).
+    llm1 = FakeEmbedder()
+    rc, out = _run_main(monkeypatch, llm1, ["--source", str(src)], capsys)
+    assert rc == 0
+    assert out.rstrip().endswith(
+        "overview=updated sources_version=1 folder_summaries=2/0/0"
+    )
+    assert set(_rows(db)) == {("MyDocs", ""), ("MyDocs", "a")}
+
+    # The owner edits the source-root description (task 03's PATCH is
+    # the writer; task 01 pins the generator's behavior, so the row is
+    # inserted directly — the ``test_import_docs_overview.py`` pattern).
+    manual_text = "Owner's own words about MyDocs."
+    db.execute(
+        text(
+            "UPDATE folder_summaries SET summary = :s, manually_edited = true"
+            " WHERE source = 'MyDocs' AND folder_path = ''"
+        ),
+        {"s": manual_text},
+    )
+    db.commit()
+    root_stamp_before = _updated_at(db, "MyDocs", "")
+    assert root_stamp_before is not None
+
+    records: list[logging.LogRecord] = []
+
+    class _Sink(logging.Handler):
+        def emit(self, record: logging.LogRecord) -> None:
+            records.append(record)
+
+    fs_logger = logging.getLogger("app.rag.folder_summaries")
+    sink = _Sink()
+    fs_logger.addHandler(sink)
+    fs_logger.setLevel(logging.INFO)
+    try:
+        # A KB-changing re-sync (a new doc under a/) — the gate fires a
+        # full regeneration ...
+        (src / "a" / "three.md").write_text(
+            "# A Three\nAnother folder document.\n", encoding="utf-8"
+        )
+        llm2 = FakeEmbedder()
+        rc, out = _run_main(monkeypatch, llm2, ["--source", str(src)], capsys)
+    finally:
+        fs_logger.removeHandler(sink)
+
+    assert rc == 0
+    assert "added=1" in out
+    # The token STAYS 3 fields — kept_manual is a stat, not a token.
+    assert out.rstrip().endswith(
+        "overview=updated sources_version=2 folder_summaries=1/0/0"
+    )
+    # Zero folder calls for the owner's folder — only a/ (now 3 docs).
+    calls = _folder_calls(llm2)
+    assert [c[1]["content"].splitlines()[0] for c in calls] == ["Folder: MyDocs/a"]
+    # The owner's text, stamp, and flag are untouched ...
+    rows_after = _rows(db)
+    assert rows_after[("MyDocs", "")] == manual_text
+    assert _updated_at(db, "MyDocs", "") == root_stamp_before, (
+        "the manual row is never re-stamped"
+    )
+    flag = db.execute(
+        text(
+            "SELECT manually_edited FROM folder_summaries"
+            " WHERE source = 'MyDocs' AND folder_path = ''"
+        )
+    ).scalar_one()
+    assert flag is True, "the generator never clears the flag"
+    # ... while the other folder regenerates.
+    assert rows_after[("MyDocs", "a")] is not None
+    # The 4-field stats line carries the skip (PLAN §9 ample logging).
+    assert any(
+        "folder_summaries: generated=1 failed=0 pruned=0 kept_manual=1"
+        in r.getMessage()
+        for r in records
+    )
+
+
 def test_limit_run_skips_folder_generation(
     db: Session,
     src: Path,