phase: 98_sync_summary_visibility

All verification complete. Final report:

**Phase 98 — Sync summary visibility: final verification pass** (all 5 tasks already complete; implementation verified against the design, no defects found, no code changes needed)

- **Implementation checked:** `SyncStatus` phase machine (4 new keys, terminal-keep counts), `on_progress` hook in `generate_folder_summaries`, `summary_pending` on `KbTreeSource`/`KbTreeFolder` + D3 rule in `build_kb_tree`, phase-aware sync labels + pending UI in `sources.js`, `.kb-summary-pending` CSS — all match decisions D1–D5.
- **Unit + integration:** `uv run pytest` → 2184 tests, 0 failed/errors (exit 0)
- **Coverage:** `uv run pytest --cov=app --cov-report=term-missing` → **99%** on `app/` (criterion >90% ✓; `app/api/sync.py` and `app/rag/folder_summaries.py` at 100%)
- **Lint/types:** `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors, 0 warnings
- **Phase E2E (isolation):** `uv run pytest tests/e2e/test_sync_summary_visibility.py -v --no-cov` → **3 passed** (phase machine, live label, pending markers + gap-fill self-heal)
- **Regression suites (each isolated, `--no-cov`):** test_kb_tree ✓, test_ls_tree_drilldown 3 ✓, test_sync_button 3 ✓, test_sync_upload_progress 4 ✓, test_oneshot_llm_retry 2 ✓, test_local_directory_sources 3 ✓
- **Completion criteria:** all 7 verified green — status phase fields + terminal semantics; `Writing KB overview…`/`Summarizing folders… (n/m)` labels (title + aria-live); pending set == `missing_folder_summaries` (integration cross-check pinned at `test_docs_api.py:428`); CLI/`ls` byte-identity (no changes to those paths, pins green); suite/coverage/lint gates; dedicated + regression E2E. Commit left to the harness per protocol (no `git add`/`commit` run).
- **Decisions/deviations:** none — no fixes were required this pass.
- **Next pending phase:** `99_kb_tree_table_and_back_nav`.

app/schemas.py

@@ -274,12 +274,21 @@ class KbTreeFolder(BaseModel):
     (path order) followed by the direct files (catalog order) — the
     recursive union (Pydantic v2 resolves it with
     ``from __future__ import annotations``).
+
+    ``summary_pending`` (phase 98, D3 — ONE concept): true iff this
+    folder's recursive count ≥ ``MIN_DOCS_PER_FOLDER`` (2) AND it has
+    NO stored ``folder_summaries`` row (AI or manual — any row) —
+    exactly the candidate the sync-time gap-fill regenerates (the
+    :func:`app.rag.folder_summaries.missing_folder_summaries` set).
+    A < 2-document folder is never pending (it never gets a summary —
+    its one file line IS its description).
     """
 
     kind: Literal["folder"] = "folder"
     path: str
     documents: int = Field(ge=0)
     summary: str | None = None
+    summary_pending: bool = False
     children: list[KbTreeFolder | KbTreeFile] = Field(default_factory=list)
 
 
@@ -294,11 +303,21 @@ class KbTreeSource(BaseModel):
     ``(source, "")`` source-root row or null; ``children`` are the
     source's direct subfolders + direct files (same shape as a folder
     node's).
+
+    ``summary_pending`` (phase 98, D3 — ONE concept): true iff the
+    source's recursive ``documents`` count ≥ ``MIN_DOCS_PER_FOLDER``
+    (2) AND no stored ``(source, "")`` row (AI or manual — any row) —
+    exactly the source-root candidate the sync-time gap-fill
+    regenerates (the
+    :func:`app.rag.folder_summaries.missing_folder_summaries` set).
+    A registered 0-document source is never pending (there is nothing
+    to summarize).
     """
 
     name: str
     documents: int = Field(ge=0)
     summary: str | None = None
+    summary_pending: bool = False
     children: list[KbTreeFolder | KbTreeFile] = Field(default_factory=list)
 
 
@@ -308,6 +327,13 @@ class KbTree(BaseModel):
     The FULL recursive tree in ONE fetch — the RAG view (admin) drills
     client-side, zero per-level fetches (the ``00_phase.md`` "The tree
     endpoint" contract).
+
+    Every SOURCE and FOLDER node carries ``summary_pending`` (phase
+    98, D3): true iff its recursive document count ≥
+    ``MIN_DOCS_PER_FOLDER`` (2) AND it has no stored ``folder_summaries``
+    row — exactly ``missing_folder_summaries``'s candidate set (the
+    marker never drifts from the gap-fill); FILE nodes carry no flag
+    (the file table has no description column).
     """
 
     sources: list[KbTreeSource]