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_models.py

@@ -69,6 +69,54 @@ def test_chunks_reference_documents_cascade() -> None:
     assert fkc.ondelete == "CASCADE"
 
 
+def test_documents_image_context_column_contract() -> None:
+    """Phase 125 (task 01, LOCKED A1): ``documents.image_context`` —
+    TEXT, NULLABLE, NO server default. NULL is the standalone-image /
+    pre-phase-125 value (no backfill — A4 keeps those rows
+    byte-identical)."""
+    from sqlalchemy import Text as SAText
+
+    documents = Base.metadata.tables["documents"]
+    col = documents.c["image_context"]
+    assert col.nullable is True, "image_context must be NULLABLE (pre-phase rows)"
+    assert isinstance(col.type, SAText), "image_context must be TEXT"
+    assert col.server_default is None, (
+        "image_context must carry NO server default — NULL is the"
+        " standalone/pre-phase value"
+    )
+    assert col.default is None, (
+        "image_context must carry NO ORM default clause either (an"
+        " omitted column inserts NULL, the text-doc value)"
+    )
+
+
+def test_document_image_context_orm_parses() -> None:
+    """A freshly constructed ``Document`` (no DB) accepts the field in
+    both states: a set context string round-trips as-is, and
+    ``None`` (and the omitted kwarg) read NULL — the standalone-image
+    / pre-phase state."""
+    from app.models import Document
+
+    base = dict(
+        source="s",
+        path="p.md",
+        full_path="/tmp/s/p.md",
+        title="p",
+        content="c",
+        content_hash="1" * 64,
+    )
+    enriched = Document(**base, image_context="some context")
+    assert enriched.image_context == "some context"
+
+    explicit_null = Document(**base, image_context=None)
+    assert explicit_null.image_context is None
+
+    omitted = Document(**base)
+    assert omitted.image_context is None, (
+        "an omitted image_context must read NULL (the text-doc value)"
+    )
+
+
 def test_documents_unique_source_path() -> None:
     documents = Base.metadata.tables["documents"]
     uq = [