phase: 147_sync_changed_only

All defaults match. Verification complete — everything is green with no defects found.

**Phase 147 final verification pass — report**

- All 3 task files found in `complete/147_sync_changed_only/` → verification pass only; no code changes needed.
- Verified: migration 0025 (`documents.file_hash` nullable String(64), no index) + model field; fast path at top of `_index_file` (streamed 1 MiB sha256 → row lookup → `_unchanged_doc`); stamping on all three branches' create/update + shared helper; pre-phase NULL-hash fallthrough; retriever/`content_hash` untouched.
- **Tests:** `uv run pytest --cov=app --cov-report=term-missing` → 3438 passed, `app/` coverage **99%** (>90% ✓); `uv run pytest tests/e2e/test_sync_changed_only.py -v --no-cov` → 3 passed in isolation ✓; `uv run ruff check . && uv run pyright` → all checks passed, 0 errors ✓; prior-phase `tests/e2e/test_sync_button.py` → 3 passed (no regression) ✓.
- **Completion criteria:** all 7 pass — (1) column + round-trip ✓ (2) unchanged text/image/garbage-PDF/pictorial-PDF cost zero LLM/extraction/vision, `summary.unchanged` counted, rows byte-still ✓ (3) changed file re-indexes + re-stamps; bytes-changed/content-same stamps only ✓ (4) backfill/D1/D4 + log wordings pinned verbatim ✓ (5) `content_hash`/retriever byte-identical ✓ (6) all gates green ✓ (7) no prior-phase behavior change ✓.
- **Documentation:** full review of README.md (1,031 lines) and AGENTS.md against the code: every `.env.example`/code `BOR_*` var documented, all config defaults match `app/config.py`, quick-start/QA commands and referenced test files exist, `file://` URL + troubleshooting claims accurate; the phase's README "Updating the documents" edit is accurate. **Verified consistent — no changes needed.**
- **Notable:** no live-infrastructure changes (dev Postgres container used for the standard test gates only). Working tree left uncommitted per harness protocol.
- **Next pending phase:** `148_pdf_pages_in_sources`.

app/models.py

@@ -110,6 +110,21 @@ class Document(Base):
     title: Mapped[str] = mapped_column(String(500))
     content: Mapped[str] = mapped_column(Text)  # full markdown — the RAG context
     content_hash: Mapped[str] = mapped_column(String(64), index=True)  # sha256 for change detection
+    #: The sha256 of the RAW SOURCE FILE's bytes at index time (phase
+    #: 147) — the sync's change signal, compared at the top of the
+    #: importer's ``_index_file`` BEFORE the image/text/PDF dispatch
+    #: (an unchanged file costs one streamed hash + one lookup — no
+    #: extraction, no vision, no embed). NULL for pre-phase rows and
+    #: until the first post-upgrade sync stamps it (no migration
+    #: backfill is possible — a migration cannot see the source files
+    #: on disk). DISTINCT from ``content_hash`` — the FINAL indexed
+    #: content's digest (a pictorial PDF's includes vision text;
+    #: ``content_hash`` is exposed via ``app/rag/retriever.py`` and is
+    #: the dedupe/caching identity — untouched). No index: the fast
+    #: path compares it in Python after the unique ``(source, path)``
+    #: lookup — internal bookkeeping, never a query surface (unlike
+    #: ``content_hash``).
+    file_hash: Mapped[str | None] = mapped_column(String(64), default=None)
     indexed_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
     #: The document's CREATION date (phase 106, D1/D2/D3) — sourced at
     #: sync time (git last-commit date for git sources, file mtime for