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/agent.py

@@ -97,12 +97,13 @@ task 04):
    context; ``grep`` — which searches the whole document — is the
    follow-up), with the truncation recorded on the holder so the loop
    yields a :class:`app.rag.llm.ToolResultPiece` (task 02 → the SSE
-   ``tool_result`` frame + UI marker). **A7 scope clarification:** the
-   never-truncated contract is for the retrieval ``<documents>`` path
-   (the top-2 seed documents stay whole — "this should never happen");
-   the ``read`` TOOL path is the only capped read, per the owner's
-   explicit request — the two paths are distinct (retrieval seeds vs.
-   agent-requested additions). And ``grep`` greps the
+   ``tool_result`` frame + UI marker). **A6 re-revised contract
+   (phase 118, owner directive 2026-09-15):** the retrieval
+   ``<documents>`` path seeds SUMMARIES only — a suggested document's
+   full text never enters the prompt on the retrieval path; full text
+   enters the context ONLY through this ``read`` TOOL path, which is
+   the only capped read (the phase-95 cap unchanged). And ``grep``
+   greps the
    indexed documents (or the one document a combined ``source/path``
    names) for a case-insensitive fixed substring and returns up to 20
    ``source/path:line: text`` match lines (owner-locked A5, phase 68),
@@ -138,7 +139,9 @@ task 04):
    :data:`NOT_A_FOLDER`, the drill-down teaching with the argument
    echoed and the deepest existing ancestor's direct subfolders
    listed, so the model self-corrects in the next round; a document
-   already in context (seed or previously read) →
+   already READ into full-text context (phase 118: the suggested
+   seeds are summary blocks in the prompt, not full text — only an
+   already-read document is refused) →
    :data:`ALREADY_IN_CONTEXT` (phase 72, task 05 gate iteration:
    the line names the correct action — answer from the text already
    in the prompt, do not call read again — so a fired refusal ends
@@ -301,19 +304,21 @@ AGENT_TOOLS: list[dict[str, Any]] = [
         "function": {
             "name": "read",
             "description": (
-                "Do not call this tool for a document already shown in "
-                "the <documents> section, even when the user asks you to "
-                "open or read it — its full text is already in your "
-                "prompt; answer directly from it. Use it only to add a "
-                "document NOT already in <documents> to your context, "
-                "by its combined `source/path` string. Very large "
-                "documents are truncated: you receive the first part "
-                "plus a TRUNCATED notice naming how many more characters "
-                "exist — the notice is authoritative, the document did "
-                "NOT end where it stopped. Follow it and use `grep` "
-                "(pattern) to locate the rest — it searches the whole "
-                "document. Call one tool at a time — wait for this "
-                "result before your next call."
+                "The <documents> section shows the SUMMARIES of the "
+                "top-ranked documents — their full texts are NOT in "
+                "your prompt yet. Use this tool to add one of them (or "
+                "any other document) to your context, by its combined "
+                "`source/path` string, exactly as shown in the `ls` "
+                "output or the <documents> blocks. Do not re-read a "
+                "document you have already read — its full text is "
+                "already in your prompt. Very large documents are "
+                "truncated: you receive the first part plus a TRUNCATED "
+                "notice naming how many more characters exist — the "
+                "notice is authoritative, the document did NOT end "
+                "where it stopped. Follow it and use `grep` (pattern) "
+                "to locate the rest — it searches the whole document. "
+                "Call one tool at a time — wait for this result before "
+                "your next call."
             ),
             "parameters": {
                 "type": "object",
@@ -326,10 +331,9 @@ AGENT_TOOLS: list[dict[str, Any]] = [
                             "shown in the `ls` output (e.g. "
                             "'homelab/active/container_caddy/caddy.md'). "
                             "A bare document path (without the source "
-                            "name) will not resolve. Only pass a document "
-                            "NOT already shown in the <documents> "
-                            "section — it is already in your context; do "
-                            "not re-read it."
+                            "name) will not resolve. Do not re-read a "
+                            "document you have already read — its full "
+                            "text is already in your prompt."
                         ),
                     }
                 },
@@ -1152,10 +1156,15 @@ def _execute_tool(
         arg = raw_path.strip() if isinstance(raw_path, str) else ""
         if not arg:
             return MISSING_READ_ARGS
-        known = {(doc.source, doc.path) for doc in (*seed_docs, *holder.read_docs)}
+        # Phase 118 (A6): the dedupe set is ``holder.read_docs`` ONLY —
+        # the ``seed_docs`` are SUMMARY blocks in the prompt, not full
+        # text, so a FIRST read of a suggested document adds its full
+        # text through the path below; only a document ALREADY READ is
+        # refused.
+        known = {(doc.source, doc.path) for doc in holder.read_docs}
         # The dedupe check needs no DB: the split pair of a combined
-        # identity that is in context is in `known` as-is (the resolve
-        # below would find the same document).
+        # identity that is already in full-text context is in `known`
+        # as-is (the resolve below would find the same document).
         if "/" in arg:
             src, _, p = arg.partition("/")
             if (src, p) in known:
@@ -1326,11 +1335,14 @@ async def run_agent(
     the capture mechanism for new registry entries; *holder* accumulates
     the turn's ``scaffold_stripped`` total for the API layer's log line.
 
-    ``seed_docs`` are the documents the retrieval already put in context
-    (they shape the *system_prompt* the caller built); re-reading one of
-    them is rejected with :data:`ALREADY_IN_CONTEXT` (the phase-72
-    teaching line — answer from the text already in the prompt) — the
-    rejection counts in nothing, but it still consumes a round.
+    ``seed_docs`` are the suggested documents whose SUMMARY blocks the
+    caller put in the *system_prompt* (phase 118: the retrieval seeds
+    summaries, never full texts); reading one of them ADDS its full
+    text to the context through the ordinary ``read`` path — only a
+    document ALREADY READ is rejected with :data:`ALREADY_IN_CONTEXT`
+    (the phase-72 teaching line — answer from the text already in the
+    prompt); the rejection counts in nothing, but it still consumes a
+    round.
 
     DB sessions (SEC-14-04): *db_factory* is a callable that returns a
     new :class:`sqlalchemy.orm.Session` (e.g. ``lambda: SessionLocal()``).