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

@@ -22,7 +22,11 @@ unknown folder → NOT-A_FOLDER with the parent's subfolders).
 (first-slash split; a bare source name and an unknown identity get the
 no-document refusal), and ``grep`` (``all_documents`` for a whole-KB
 search, ``find_document`` for a scoped one) — both byte-identical
-across the phase-94 change.
+across the phase-94 change. Phase 106 (D5): the ``ls`` FILE line ends
+with the appended `` | date: YYYY-MM-DD`` field and the ``read``
+result carries the ``date: YYYY-MM-DD`` second line (first line
+byte-identical) — the fixture documents carry a fixed ``created_at``
+so the pins stay deterministic.
 
 Requires:  podman compose up -d db
 """
@@ -32,6 +36,7 @@ import asyncio
 import uuid
 from collections.abc import AsyncIterator, Iterator
 from copy import deepcopy
+from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Any, cast
 
 import pytest
@@ -53,6 +58,11 @@ from app.rag.llm import (
 if TYPE_CHECKING:
     from app.rag.scaffolding import ScaffoldingFilter
 
+#: The fixture documents' fixed creation date (phase 106, D5) — the
+#: ``ls`` file line and the ``read`` second line format its UTC date
+#: part; a fixed value keeps the pins deterministic.
+_FIXTURE_CREATED_AT = datetime(2024, 6, 15, 12, 0, 0, tzinfo=UTC)
+
 
 def _doc(db: Session, source: str, path: str, title: str, content: str) -> Document:
     doc = Document(
@@ -63,6 +73,7 @@ def _doc(db: Session, source: str, path: str, title: str, content: str) -> Docum
         title=title,
         content=content,
         content_hash="0" * 64,
+        created_at=_FIXTURE_CREATED_AT,
     )
     db.add(doc)
     return doc
@@ -121,8 +132,8 @@ def test_source_document_rows_order_by_path_within_the_source(kb, db) -> None:
     db.commit()
 
     assert agent._source_document_rows(db, "Zeta") == [
-        ("a/first.md", "Zeta A"),
-        ("b/second.md", "Zeta B"),
+        ("a/first.md", "Zeta A", "2024-06-15"),
+        ("b/second.md", "Zeta B", "2024-06-15"),
     ]
 
 
@@ -355,7 +366,7 @@ def test_ls_source_scope_lists_root_folder_through_run_agent(kb, registry, db) -
         "  backups/ — 2 documents: Backup notes.\n"
         "  networking/ — 1 documents\n"
         "\n"
-        "source: Homelab | path: readme.md | title: Readme"
+        "source: Homelab | path: readme.md | title: Readme | date: 2024-06-15"
     )
     assert holder.tool_calls == 1
     assert holder.read_docs == []
@@ -393,8 +404,8 @@ def test_ls_nested_folder_scope_drills_one_level_through_run_agent(
     assert llm2.requests[1][0][3]["content"] == (
         "Homelab/networking/lan — 2 documents, 0 folders:\n"
         "\n"
-        "source: Homelab | path: networking/lan/a.md | title: A\n"
-        "source: Homelab | path: networking/lan/b.md | title: B"
+        "source: Homelab | path: networking/lan/a.md | title: A | date: 2024-06-15\n"
+        "source: Homelab | path: networking/lan/b.md | title: B | date: 2024-06-15"
     )
     assert holder2.tool_calls == 1
 
@@ -411,8 +422,12 @@ def test_ls_folder_file_cap_through_run_agent(kb, registry, db) -> None:
     content = llm.requests[1][0][3]["content"]
     lines = content.splitlines()
     assert lines[0] == "Homelab/big — 51 documents, 0 folders:"
-    assert lines[2] == "source: Homelab | path: big/f000.md | title: T0"
-    assert lines[51] == "source: Homelab | path: big/f049.md | title: T49"
+    assert lines[2] == (
+        "source: Homelab | path: big/f000.md | title: T0 | date: 2024-06-15"
+    )
+    assert lines[51] == (
+        "source: Homelab | path: big/f049.md | title: T49 | date: 2024-06-15"
+    )
     assert lines[52] == (
         "…and 1 more documents in this folder — use grep (pattern) to "
         "find a specific one."
@@ -491,8 +506,12 @@ def test_read_combined_path_through_run_agent(kb, db) -> None:
 
     holder, llm = _run_call(db, "read", {"path": "Alpha/deep/nested/doc.md"})
 
+    # Phase 106 (D5): the date rides every read — the SECOND line (the
+    # first line stays the byte-identical header).
     assert llm.requests[1][0][3]["content"] == (
-        "Document Alpha/deep/nested/doc.md:\nFULL-TEXT"
+        "Document Alpha/deep/nested/doc.md:\n"
+        "date: 2024-06-15\n"
+        "FULL-TEXT"
     )
     assert holder.tool_calls == 1
     assert holder.read_docs == [created]
@@ -563,9 +582,12 @@ def test_read_bare_path_single_source_suggestion_then_corrected_read(kb, db) ->
     )
     assert llm.requests[1][1] == AGENT_TOOLS
     # Round 2: the corrected combined identity succeeds — the full
-    # content, the holder records the row, and it counts.
+    # content (plus the phase-106 D5 date line), the holder records the
+    # row, and it counts.
     assert llm.requests[2][0][5]["content"] == (
-        "Document Alpha/deep/nested/doc.md:\nFULL-TEXT"
+        "Document Alpha/deep/nested/doc.md:\n"
+        "date: 2024-06-15\n"
+        "FULL-TEXT"
     )
     assert llm.requests[2][1] == AGENT_TOOLS
     assert holder.read_docs == [created]
@@ -598,7 +620,9 @@ def test_read_bare_path_two_sources_one_of_suggestion_then_corrected_read(
         "No document at 'shared/x.md' — did you mean one of: "
         "'Alpha/shared/x.md', 'Beta/shared/x.md'?"
     )
-    assert llm.requests[2][0][5]["content"] == "Document Alpha/shared/x.md:\nA-TEXT"
+    assert llm.requests[2][0][5]["content"] == (
+        "Document Alpha/shared/x.md:\ndate: 2024-06-15\nA-TEXT"
+    )
     assert holder.read_docs == [a]
     assert holder.tool_calls == 1  # only the corrected read executed