phase: 106_document_dates

Everything is verified green. Final report:

**Phase 106 — Document dates (final verification pass; all 10 tasks already complete)**

- Verified all phase artifacts: alembic `0020` (dev DB at `0020`), `doc_dates.py`, git `file_commit_dates`, importer `doc_dates_by_root`/`dates_updated`, both entry-point wirings, date APIs + tree `created_at`/`updated_at`, LLM surfaces (prompt block, `read` line 2, appended `ls` field), `apply_recency_boost` in `retrieve()`, UI columns/badge, admin editor, mock-LLM regex — all present and correct; no defects found, no fixes needed.
- `uv run pytest --cov=app --cov-report=term-missing` → **2299 passed, TOTAL 99%** (>90% ✓)
- `uv run pytest tests/e2e/test_document_dates.py -v --no-cov` → **6/6 passed** in isolation (DB up)
- 12 regression E2E suites (retrieval_quality, whole_document_context, agent_document_tools, ls_tree_drilldown, read_truncation_cap, kb_tree, kb_tree_nav, document_viewer, edit_summaries, import_documents, sync_button, hidden_folders_toggle, smoke) → **all green in isolation**
- `uv run ruff check .` → clean; `uv run pyright` → **0 errors, 0 warnings**

**Completion criteria:** 1) non-null `created_at` + 0020 upgrade/downgrade on dev DB ✓ (real-Alembic integration tests) 2) sync refresh/older/manual-persists/content-reset/no sources_meta bump ✓ 3) zip/tar mtime + future→today ✓ 4) LLM date surfaces + cross-check ✓ 5) UI Created/Updated/badge positions ✓ 6) admin editor set+revert round-trip ✓ 7) old-correct-beats-new-similar (defaults & boost-off) + near-tie + `BOR_RECENCY_BOOST=0` byte-identical ✓ 8) full gate ✓ 9) commit/phase-move — left to harness per instructions.

- **Notable:** recency default tuned 0.001 → **0.0007** (task 07 step 5 explicitly permits; measured margins recorded in `test_recency_boost.py` docstring).
- **Next pending phase:** none — `todo/` holds only this phase.

tests/integration/test_chat_api.py

@@ -18,6 +18,7 @@ import math
 import re
 import uuid
 from collections.abc import Iterator
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
 
@@ -40,6 +41,13 @@ from app.rag.retriever import TRUNCATION_MARKER
 from app.schemas import ChatDoneEvent, SourceRef
 from tests.conftest import ADMIN_PASSWORD
 
+#: The fixture documents' fixed creation date (phase 106, D5): the
+#: ``read`` result's second line is the row's ``created_at`` UTC date
+#: part — a fixed value keeps the read-result pins deterministic
+#: (instead of the ``now()`` server default of a bare insert).
+_FIXTURE_CREATED_AT = datetime(2024, 6, 15, 12, 0, 0, tzinfo=UTC)
+
+
 if TYPE_CHECKING:
     from app.rag.scaffolding import ScaffoldingFilter
 
@@ -663,6 +671,7 @@ pins the agent-loop yield order on the real prompt path."""
         title="Big Doc",
         content=content,
         content_hash="1" * 64,
+        created_at=_FIXTURE_CREATED_AT,
     )
     db.add(doc)
     db.commit()
@@ -695,7 +704,11 @@ pins the agent-loop yield order on the real prompt path."""
         ]
         assert tool_msgs, "the executed read must be appended as a tool message"
         body = tool_msgs[-1]["content"]
-        assert body.startswith("Document docs/big.md:\n" + content[:cap])
+        # Phase 106, D5: the date rides every read — the SECOND line
+        # (first line byte-identical — the mock's header contract).
+        assert body.startswith(
+            "Document docs/big.md:\ndate: 2024-06-15\n" + content[:cap]
+        )
         assert TRUNCATION_MARKER in body
         assert (
             READ_TRUNCATION_NOTICE.format(shown=cap, total=len(content)) in body
@@ -749,6 +762,7 @@ marker in the model's context."""
         title="Fits Doc",
         content=content,
         content_hash="2" * 64,
+        created_at=_FIXTURE_CREATED_AT,
     )
     db.add(doc)
     db.commit()
@@ -770,14 +784,18 @@ marker in the model's context."""
         # No ToolResultPiece, no holder entry.
         assert not any(isinstance(p, ToolResultPiece) for p in pieces)
         assert holder.read_truncations == []
-        # The model's context is the whole document, byte-identical to
-        # the pre-phase-95 read result (no marker, no notice). (The fake
-        # aliases the mutated messages list, so take the last tool msg.)
+        # The model's context is the whole document, the pre-phase-95
+        # read result plus the phase-106 D5 date line (no marker, no
+        # notice). (The fake aliases the mutated messages list, so
+        # take the last tool msg.)
         tool_msgs = [
             m for r in scripted.seen_messages for m in r if m.get("role") == "tool"
         ]
         assert tool_msgs, "the executed read must be appended as a tool message"
-        assert tool_msgs[-1]["content"] == "Document docs/fits.md:\n" + content
+        assert (
+            tool_msgs[-1]["content"]
+            == "Document docs/fits.md:\ndate: 2024-06-15\n" + content
+        )
         assert TRUNCATION_MARKER not in tool_msgs[-1]["content"]
         # Still a successful read.
         assert holder.tool_calls == 1
@@ -800,6 +818,7 @@ def _insert_big_doc(db, content: str) -> Document:
         title="Big Read Doc",
         content=content,
         content_hash="3" * 64,
+        created_at=_FIXTURE_CREATED_AT,
     )
     db.add(doc)
     db.commit()
@@ -890,7 +909,8 @@ def test_truncated_read_streams_tool_result_frame_after_tool_frame(
     ]
     assert tool_msgs
     body = tool_msgs[-1]["content"]
-    assert body.startswith(f"Document docs/big-read.md:\n{content[:cap]}")
+    # Phase 106, D5: the date rides every read — the SECOND line.
+    assert body.startswith(f"Document docs/big-read.md:\ndate: 2024-06-15\n{content[:cap]}")
     assert TRUNCATION_MARKER in body
     assert READ_TRUNCATION_NOTICE.format(shown=cap, total=len(content)) in body
     # The truncated read is still a SUCCESSFUL call — cited in done.
@@ -956,7 +976,10 @@ def test_untruncated_read_streams_no_tool_result_frame(
         m for r in scripted.seen_messages for m in r if m.get("role") == "tool"
     ]
     assert tool_msgs
-    assert tool_msgs[-1]["content"] == "Document docs/big-read.md:\n" + content
+    assert (
+        tool_msgs[-1]["content"]
+        == "Document docs/big-read.md:\ndate: 2024-06-15\n" + content
+    )
     assert TRUNCATION_MARKER not in tool_msgs[-1]["content"]