phase: 125_image_anchor_context

All completion criteria verified. The repository is left functional with all changes in the working tree (no commits made, per the harness protocol).

## Final report — phase 125 `image_anchor_context` (verification pass)

All 6 tasks were already complete; this pass verified every criterion and ran the full gates:

- **Migration 0023** `documents.image_context` (TEXT nullable, reversible) — applied (`alembic current` = 0023 head); round-trip test (4 passed) exercises real upgrade → downgrade 0022 → upgrade.
- **Criterion 1** (referenced image enriched + context line in retrieval): integration `test_markdown_referenced_image_gets_context_and_enriched_chunks` + E2E `test_sync_enriches_the_image_doc_with_markdown_context`, `test_chat_answer_quotes_the_context_line` (wire prompt pinned: `<document>` block leads with the one-line `Referenced in …: "alt"` line) — verified present and passing.
- **Criterion 2** (standalone image byte-identical): E2E `test_standalone_*` (NULL `image_context`, block body exactly the bare description, no `Referenced in` anywhere in the prompt) + unit `test_describe_image_without_context_is_byte_identical` — passing.
- **Criterion 3** (markdown-first: record stored on markdown doc, image picks up context later): integration `test_markdown_indexed_before_image_stores_record_and_image_picks_it_up` + post-index enrichment pass test (markdown file gone from disk) — passing.
- **Gates:** `uv run pytest` → 2938 passed, exit 0 · `uv run pytest --cov=app --cov-report=term-missing` → exit 0, TOTAL **99%** (>90%) · `uv run ruff check .` → All checks passed · `uv run pyright` → 0 errors, 0 warnings.
- **Phase E2E in isolation:** `uv run pytest tests/e2e/test_image_anchor_context.py -v --no-cov` → 4 passed.
- **Mock-LLM change regression check:** neighboring image E2E suites green in isolation — `test_smoke` (3), `test_image_documents` (16), `test_chat_image_questions` (17), `test_answer_images` (17).
- No defects found; no code changes needed. No live-infrastructure changes (local dev DB only). No commit made (harness commits).
- Next pending phase: check `.agents/phases/todo/` after the harness moves this phase.

tests/unit/test_image_documents.py

@@ -283,11 +283,21 @@ def _patch_description(
     """Pin the task-02 seam (``importer._describe_or_skip``) to
     *description* and record the BYTES it is handed (the digest-rule
     pin). Task 03 replaces the seam's body — the importer-side
-    mechanics under test here do not change with it."""
+    mechanics under test here do not change with it. Phase 125 (task
+    03) widened the seam with the optional ``context`` kwarg (the
+    markdown reference context) — the fake accepts (and ignores) it:
+    these fixtures carry no image references, so the seam gets
+    ``context=None``."""
     handed: list[bytes] = []
 
     async def _fake(
-        llm: importer.Embedder, *, data: bytes, source: str, rel: str, full_path: Path
+        llm: importer.Embedder,
+        *,
+        data: bytes,
+        source: str,
+        rel: str,
+        full_path: Path,
+        context: str | None = None,
     ) -> str | None:
         handed.append(data)
         return description
@@ -524,7 +534,13 @@ def test_changed_image_deletes_the_stale_copy_before_replacing(
     state = {"desc": "v1 description"}
 
     async def _fake(
-        llm: importer.Embedder, *, data: bytes, source: str, rel: str, full_path: Path
+        llm: importer.Embedder,
+        *,
+        data: bytes,
+        source: str,
+        rel: str,
+        full_path: Path,
+        context: str | None = None,
     ) -> str | None:
         handed.append(data)
         return state["desc"]