phase: 118_summary_seed_context

**Phase 118 final verification pass — complete.** All criteria verified; 4 pre-existing defects found and fixed.

- **Verified:** summary-seed wiring (`select_suggested` top-5 no-floor → summary blocks, no full text in HIGH prompt), all-doc markdown summaries + NULL backfill (`summary_backfilled`, no `sources_meta` bump), `read` adds full text with `read_docs`-only dedupe, `done.sources` = suggested+read / durable record = suggested+related+read + `suggested=N` log line (seen live in E2E), byte-locked PERSONA/LOW/TOOLS_SECTION, battery gate PASS recorded in `TOOL_CALLING_TESTING.md` §10 (turbo 2026-09-16: 1/2/4 GREEN, cond-3 reported 9/10 per A7, contract 21/21, caps 0).
- **Defects fixed (all pre-existing, none phase-118):** ① `ChatMessage` schema missing the phase-113 `related` key → `extra="forbid"` 422'd every done-time auto-save of grounded turns with a related tier, leaving `message_count=1` (root cause of `test_share_chat` 3F; browser-level instrumentation proved the PUT 422) — added the field + unit/integration pins; ② `test_theme_semantic_completion` pins stale vs phase-117 debox (border/chip removed) — re-targeted to assert border/chip *absence*; ③ `test_header_consistency` `<26`px pin red on 26.125px native date-input line — bound relaxed to `<34` (wrap-detection intent kept); ④ `test_navbar_refresh` bor.chat.v1 key set updated for `related`.
- **Test/lint/coverage:** `uv run pytest --cov=app --cov-report=term-missing` → **2506 passed, app/ 99%** (>90%); `uv run ruff check . && uv run pyright` → clean, 0 errors.
- **E2E:** new story suite in isolation → **2 passed**; full 103-suite matrix sweep (each isolated) → **all 103 green** after the fixes; `test_share_chat` 4 passed, `test_theme_semantic_completion` 8 passed, `test_header_consistency` 3 passed, `test_navbar_refresh` 7 passed.
- **Deviations:** none from LOCKED decisions. Note: orphaned diagnostic uvicorn processes briefly made E2E sessions exercise stale code — killed and re-verified; a sweep-regenerated tracked screenshot was restored. No commits made (harness commits).
- **Completion criteria:** all 7 ✅ (commit/phase-move is the harness's step).
- **Next pending phase:** none — `todo/` holds only this phase's overview pending the harness move.

app/rag/importer.py

@@ -10,7 +10,8 @@ the two-phase upsert:
 2. embed the new chunks in batches and attach the vectors
 3. commit — one transaction per file, so a failed embedding leaves the
    database untouched and the file is simply retried on the next run
-4. non-markdown files only (phase 30): generate a ``lite``-model summary
+4. every file (phase 30; phase 118, A2: markdown included — the
+   non-markdown-only scope is retired): generate a ``lite``-model summary
    and, best-effort, store it on ``documents.summary`` plus one extra
    embedded chunk (``is_summary``, position −1). The document row and its
    content chunks are already committed at this point, so a summary
@@ -42,6 +43,17 @@ guard) and counted in ``summary.dates_updated`` — unless the row
 carries the owner's manual correction (``created_at_manual``, D1), which
 the sync never touches.
 
+NULL-summary backfill (phase 118, A2): an UNCHANGED file (same
+``content_hash``) whose ``documents.summary`` is still NULL — a
+pre-phase-30 row, or an earlier fail-soft miss — gets the same
+best-effort summary pass on every sync until it sticks. A success counts
+``summary_backfilled`` (never ``summaries``) and touches nothing else: no
+content re-embed, no added/updated/pruned count — so no
+``sources_meta`` bump, no KB-overview/folder-summary regeneration. The
+backfill runs BEFORE the ``created_at_manual`` early-return (the manual
+flag protects the DATE only, D1) and the strict ``is None`` check leaves
+owner-set summaries (even empty strings, phase 57) alone.
+
 ``import_sources`` accepts an optional per-file ``progress`` callback
 (phase 64, task 01) reporting the file being processed right now.
 """
@@ -99,12 +111,18 @@ class ImportSummary:
     errors: int = 0
     chunks: int = 0
     embed_batches: int = 0
-    #: Non-markdown files whose lite summary was generated + indexed
-    #: (phase 30). One ``is_summary`` chunk per success.
+    #: Files whose lite summary was generated + indexed (phase 30; phase
+    #: 118, A2: every A9 format, markdown included). One ``is_summary``
+    #: chunk per success.
     summaries: int = 0
-    #: Non-markdown files whose summary generation failed (best-effort —
-    #: the document is still indexed, without a summary).
+    #: Files whose summary generation failed (best-effort — the document
+    #: is still indexed, without a summary).
     summary_errors: int = 0
+    #: Unchanged docs whose NULL summary was backfilled (phase 118, A2) —
+    #: one ``is_summary`` chunk per success; the content is untouched, so
+    #: a backfill NEVER counts added/updated/pruned (no
+    #: ``sources_meta`` bump, no overview/folder-summary regeneration).
+    summary_backfilled: int = 0
     #: Files whose ``created_at`` was refreshed on the UNCHANGED path —
     #: content untouched, date re-sourced (phase 106, D4: the date may
     #: go OLDER; a date-only refresh NEVER counts added/updated/pruned,
@@ -125,7 +143,7 @@ class ImportSummary:
         logger.info(
             "import: summary files=%d added=%d updated=%d unchanged=%d pruned=%d "
             "errors=%d chunks=%d embed_batches=%d summaries=%d summary_errors=%d "
-            "dates_updated=%d formats=%s",
+            "summary_backfilled=%d dates_updated=%d formats=%s",
             self.files,
             self.added,
             self.updated,
@@ -136,6 +154,7 @@ class ImportSummary:
             self.embed_batches,
             self.summaries,
             self.summary_errors,
+            self.summary_backfilled,
             self.dates_updated,
             self.format_counts(),
         )
@@ -442,6 +461,20 @@ async def _index_file(
     if doc is not None and doc.content_hash == digest:
         summary.unchanged += 1
         logger.info("import: unchanged source=%s path=%s", source, rel)
+        # Phase 118 (A2): an unchanged doc whose summary is still NULL
+        # (a pre-phase-30 row, or an earlier fail-soft miss) gets a
+        # summary-only backfill — one ``is_summary`` chunk, no content
+        # re-embed, and NEVER an added/updated/pruned count (so no
+        # ``sources_meta`` bump, no overview/folder-summary
+        # regeneration). Strict ``is None``: an empty-string summary is
+        # owner-set (phase 57) and is never overwritten. BEFORE the
+        # manual-date early-return: ``created_at_manual`` protects the
+        # DATE only (phase 106, D1), not the summary.
+        if doc.summary is None:
+            await _store_summary(
+                session, doc=doc, source=source, rel=rel, content=content,
+                llm=llm, summary=summary, backfill=True,
+            )
         if doc.created_at_manual:
             # D1/D4: the owner's correction survives the sync — no
             # write at all (the phase-97 ``manually_edited`` precedent).
@@ -536,10 +569,11 @@ async def _index_file(
     summary.chunks += len(chunks_text)
     logger.info("import: %s source=%s path=%s chunks=%d", verb, source, rel, len(chunks_text))
 
-    # Phase 30: markdown is already natural language, so only the other A9
-    # formats (txt, yaml, yml, json, py) get a ``lite``-model summary.
-    if full_path.suffix.lower() in (".md", ".markdown"):
-        return
+    # Phase 30; phase 118 (A2, 2026-09-15): EVERY new/changed document
+    # gets a ``lite``-model summary — markdown included. Phase 30's
+    # "markdown is already natural language" exclusion is retired: the
+    # summary is the retrieval seed context (the phase-118 suggestion
+    # blocks), not a formatting convenience.
     await _store_summary(
         session, doc=doc, source=source, rel=rel, content=content, llm=llm, summary=summary
     )
@@ -554,6 +588,7 @@ async def _store_summary(
     content: str,
     llm: Embedder,
     summary: ImportSummary,
+    backfill: bool = False,
 ) -> None:
     """Best-effort ``lite`` summary for one already-committed document.
 
@@ -569,6 +604,11 @@ async def _store_summary(
     :class:`EmbeddingError` only rolls back the summary rows — the file
     stays indexed, without a summary, and the failure is counted in
     ``summary_errors`` (PLAN phase 30).
+
+    ``backfill`` (phase 118, A2): the unchanged-doc NULL-summary path —
+    a success counts ``summary_backfilled`` instead of ``summaries``
+    (the doc content is untouched, so the import's KB-change signal must
+    not move); the rest of the mechanics are identical.
     """
     try:
         text = await generate_summary(llm, source=source, path=rel, content=content)
@@ -588,8 +628,18 @@ async def _store_summary(
         # ``expire_on_commit=False`` — reflects the committed state.
         doc.chunks.append(chunk)
         session.commit()
-        summary.summaries += 1
-        logger.info("import: summary source=%s path=%s chars=%d", source, rel, len(text))
+        if backfill:
+            # Phase 118 (A2): the backfill counts itself apart from fresh
+            # imports — the doc content is unchanged, so ``summaries``
+            # (a KB-change signal) must not move.
+            summary.summary_backfilled += 1
+            logger.info(
+                "import: summary-backfill source=%s path=%s chars=%d",
+                source, rel, len(text),
+            )
+        else:
+            summary.summaries += 1
+            logger.info("import: summary source=%s path=%s chars=%d", source, rel, len(text))
     except (LLMError, EmbeddingError) as e:
         session.rollback()
         summary.summary_errors += 1