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.

app/config.py

@@ -185,6 +185,28 @@ class Settings(BaseSettings):
     hybrid_vector_candidates: int = 100
     hybrid_lexical_candidates: int = 30
     rrf_k: int = 60
+    #: Recency boost on the RRF-fused retrieval score (phase 106, D6): the
+    #: MAXIMUM additive score a zero-age document gets —
+    #: ``fused + recency_boost * exp(-age_days / recency_half_life_days)``
+    #: (``app.rag.retriever.apply_recency_boost``, applied in
+    #: ``retrieve()`` after ``fuse()``). ``0`` = off — the pre-phase
+    #: ranking is byte-identical (the kill switch); negative values fail
+    #: startup loudly (the ``agent_max_rounds`` validator pattern).
+    #: 0.0007 ≈ a 2-3 rank head start on a 60+ RRF scale (rank 1 vs 2
+    #: in one list differs by ~0.00026, rank 1 vs 10 by ~0.0021) —
+    #: enough to break near-ties toward the newer document, far below
+    #: the gap between a document that answers and one that merely
+    #: resembles (the phase-106 fine-line battery pins the measured
+    #: margin). The design starting point was 0.001; the battery's
+    #: 3×-margin requirement tuned it down here (task 07 step 5) — on
+    #: the k=60 scale a 0.001 boost would flip the pinned owner
+    #: scenario (older-correct vs newer-similar).
+    recency_boost: float = 0.0007
+    #: Age (days) over which the recency boost decays (phase 106, D6):
+    #: the boost multiplies by ``e**-1`` ≈ 0.37 per ``recency_half_life_days``
+    #: of document age (full weight at age 0, ``weight/e`` at one
+    #: half-life). ``<= 0`` fails startup loudly (same validator family).
+    recency_half_life_days: int = 365
 
     # --- Admin & sign-in (phase 16; A10 revised 2026-08-22) ---
     # Single-admin auth via a signed session cookie (Starlette
@@ -351,6 +373,25 @@ class Settings(BaseSettings):
             raise ValueError("history_max_chars must be >= 0 (chars)")
         return v
 
+    @field_validator("recency_boost")
+    @classmethod
+    def _recency_boost_non_negative(cls, v: float) -> float:
+        """``0`` is the kill switch (pre-phase ranking byte-identical) — a
+        negative boost would demote fresh documents, the exact opposite
+        of D6 (the ``agent_max_rounds`` pattern, phase 106)."""
+        if v < 0:
+            raise ValueError("recency_boost must be >= 0 (0 = off)")
+        return v
+
+    @field_validator("recency_half_life_days")
+    @classmethod
+    def _recency_half_life_days_positive(cls, v: int) -> int:
+        """``0``/negative would divide the decay exponent by zero — fail
+        loud at startup (the ``agent_max_rounds`` pattern, phase 106)."""
+        if v <= 0:
+            raise ValueError("recency_half_life_days must be > 0 (days)")
+        return v
+
     @field_validator("docs_branch", "docs_base_branch")
     @classmethod
     def _docs_branch_tokens(cls, v: str, info: ValidationInfo) -> str: